diff --git a/.github/bump-callers/README.md b/.github/bump-callers/README.md index aac7d6c0..f7145681 100644 --- a/.github/bump-callers/README.md +++ b/.github/bump-callers/README.md @@ -29,6 +29,7 @@ forward automatically instead of silently drifting commits behind. |---|---|---|---| | [`bump-cursor-review-callers.yml`](../workflows/bump-cursor-review-callers.yml) | `cursor-review.yml`, `cursor-review/**` or `scripts/check-pr-size/**` (minus its `*_test.go`, which no caller executes) | `CURSOR_REVIEW_CALLERS` | non-empty (hard-fails if empty) | | [`bump-agents-md-callers.yml`](../workflows/bump-agents-md-callers.yml) | `agents-md-integrity.yml` or `agents-md-integrity/**` | `AGENTS_MD_CALLERS` | empty `[]` (grows as callers land) | +| [`bump-coderabbit-config-callers.yml`](../workflows/bump-coderabbit-config-callers.yml) | `coderabbit-config-validate.yml` or `coderabbit-config/**` | `CODERABBIT_CONFIG_CALLERS` | empty `[]` (grows as callers land) | | [`bump-pr-size-callers.yml`](../workflows/bump-pr-size-callers.yml) | `pr-size.yml` or `scripts/check-pr-size/**` (minus its `*_test.go`, which no caller executes) | `PR_SIZE_CALLERS` | empty `[]` (grows as callers land) | | [`bump-pr-risk-callers.yml`](../workflows/bump-pr-risk-callers.yml) | `pr-risk.yml` or `scripts/pr-risk/**` (minus its `tests/` and `README.md`, which no caller executes) | `PR_RISK_CALLERS` | non-empty (hard-fails if empty) | | [`bump-pr-derisk-callers.yml`](../workflows/bump-pr-derisk-callers.yml) | `pr-derisk.yml`, `scripts/pr-derisk/**` **or `scripts/pr-risk/**`** (minus both `tests/` and `README.md`) — a `/derisk` run executes the pr-risk grader as well as the planner, so a grader change is consumer-visible on this fleet too | `PR_RISK_CALLERS` **(shared — filtered to `ci-pr-derisk.yml`)** | **may select nothing** (no callers enrolled yet — flip `ALLOW_EMPTY` to `false` with the first enrolment) | diff --git a/.github/coderabbit-config/README.md b/.github/coderabbit-config/README.md new file mode 100644 index 00000000..8ab1e4e4 --- /dev/null +++ b/.github/coderabbit-config/README.md @@ -0,0 +1,125 @@ +# coderabbit-config + +The checker behind [`coderabbit-config-validate.yml`](../workflows/coderabbit-config-validate.yml), +plus the vendored schema it validates against. Consumer repos carry only a thin +caller; everything here is loaded at run time from the SHA a caller pins, so a PR +can never rewrite the check that judges it — nor swap the schema it is graded +against. + +## What it catches, and why CI has to + +CodeRabbit rejects an invalid `.coderabbit.yaml` **whole**. Not the offending +field — the entire file. The review then runs on org-wide UI defaults, so every +reviewer instruction, path filter, path instruction and WIP-skip rule in the file +goes silently inert. The file still reads fine; only the validator sees the loss. + +And the feedback arrives one PR late, on the wrong diff: CodeRabbit validates the +config on the **base** branch, not the PR head. The PR that breaks the file goes +green; the breakage surfaces on the *next* PR, attributed to a change that did not +cause it. That displacement is what makes this a machine check rather than a +convention — the same field on the same repo was fixed twice in six days by two +independent tickets, which is the signature of a failure nothing detects. + +## Severity, and why it is split + +The split mirrors what CodeRabbit itself does with each class of problem, not what +a schema library calls "invalid": + +| Class | Severity | Because | +|---|---|---| +| YAML parse error | error | CodeRabbit cannot read the file at all. | +| `maxLength` violation | error | File-rejecting. The schema carries **14** per-field caps, 50 → 20,000 chars. | +| type / enum error | error | File-rejecting. | +| unknown / additional property | **warning** | CodeRabbit *strips* an unrecognized key rather than rejecting the file. Only where the schema closes the object — see below. | +| config path that is not a regular file, or > 512 KiB | exit 2 | "I could not check" must never look like a pass. A path resolving outside the repo root (symlinks resolved) is refused the same way. | + +`strict_unknown_keys: true` escalates the last row to an error for a repo that has +cleaned up and wants to stay clean. + +**How far the unknown-key row reaches.** It fires where the schema CLOSES an +object — the document root, `knowledge_base.mcp`, and the two tool objects that +declare `additionalProperties: false`. Most nested objects (`reviews`, `chat`, +`knowledge_base`, `code_generation`, the individual tool configs) are open in +upstream's schema, so a typo *inside* one — `reviews.profil`, or +`golangci-lint.enabld` — produces no finding, with or without +`strict_unknown_keys`. That is a real gap and not a claim this checker makes: +what it catches is a key in the wrong PLACE, which is the failure that actually +recurred here. Widening it means cross-checking parsed keys against the schema +index rather than waiting for jsonschema to complain. + +A stripped key is not a cosmetic problem. The recurring instance is a `tools:` +block written at the document root instead of under `reviews:` — the schema root +is `additionalProperties: false`, so the whole block is dropped and every setting +in it reverts to the schema default, which is often the *opposite* of what was +written. `reviews.tools.golangci-lint.enabled` defaults to `true`, so a root-level +`enabled: false` runs the linter it was written to disable. Three org repos +carried exactly that shape when this landed. + +## Why file size is the wrong invariant + +The obvious cheap check — "fail if `.coderabbit.yaml` gets too big" — would gate +nothing. There is no whole-document size cap in the schema, only the 14 per-field +ones, and size is uncorrelated with validity: the invalid config that started this +was 2,198 bytes while a valid one next to it was 4,826. Across the org sweep there +were **zero** `maxLength` violations and three misplaced-key repos, so a size check +would have found none of the real problems and none of the historical one. + +## Why the schema is vendored + +`schema.v2.json` is a committed copy of +`https://coderabbit.ai/integrations/schema.v2.json`. Validation never fetches it. + +- A live fetch makes every consumer's CI depend on a third-party endpoint. +- An upstream tightening — a `maxLength` lowered, a property removed — would turn + CI red across every enrolled repo with no change on our side and no PR to point + at. + +[`refresh-coderabbit-schema.yml`](../workflows/refresh-coderabbit-schema.yml) +covers the cost of vendoring: weekly it fetches upstream, compares semantically +(so a whitespace-only reserialization is not "drift"), and opens a reviewable PR +with a summary that leads on tightened caps — the one drift class that can +retroactively invalidate a config nobody touched. Merging it trips +`bump-coderabbit-config-callers.yml`, which rolls the pinned caller fleet forward. + +**Any fetch of that URL must use `curl -fsSL`.** It 301-redirects, and a bare +`curl` writes a ~167-byte HTML redirect stub. Both `check_coderabbit_config.py` +and `schema_drift.py` refuse a file that is not a JSON Schema object rather than +treating it as "no drift" or "everything valid" — a check that cannot fail is +worse than no check. + +## The dependency + +This repo is otherwise stdlib-only, deliberately. This directory is the one +exception and neither half has a stdlib answer: there is no YAML parser in the +standard library, and the point of the check is to reproduce the verdict +CodeRabbit's own Draft 2020-12 validator reaches — a hand-written subset validator +would agree with the real one until it didn't, and the day it diverged the check +would either gate nothing or fail a valid config. + +So the dependency is pinned hard instead: exact versions with sha256 hashes in +[`requirements.txt`](requirements.txt), installed with `--require-hashes`, and +watched by Dependabot (`pip` ecosystem in `.github/dependabot.yml`) so the pins do +not rot. + +## Files + +| File | What it is | +|---|---| +| `check_coderabbit_config.py` | The validator. `--root`, `--config`, `--schema`, `--strict-unknown-keys`. Exit 0 pass / 1 invalid / 2 could-not-run. | +| `schema.v2.json` | The vendored schema. Never edit by hand — let the refresh job propose the bump. | +| `schema_drift.py` | Semantic comparison + Markdown drift summary for the refresh PR. Exit 0 no-drift / 1 drifted / 2 unusable input. | +| `requirements.txt` | The hash-pinned PyYAML + jsonschema set. | +| `tests/` | Unit tests, run by `test-coderabbit-config-validate.yml`. | + +## Run it locally + +```bash +python3 -m venv /tmp/crvenv +/tmp/crvenv/bin/pip install --require-hashes --only-binary=:all: \ + -r .github/coderabbit-config/requirements.txt # linux/cp312 wheels +/tmp/crvenv/bin/python .github/coderabbit-config/check_coderabbit_config.py --root . +/tmp/crvenv/bin/python -m unittest discover -s .github/coderabbit-config/tests -p 'test_*.py' -v +``` + +The hashes pin the cp312 / manylinux x86_64 wheels CI installs, so on another +platform install the same two versions without `--require-hashes` instead. diff --git a/.github/coderabbit-config/check_coderabbit_config.py b/.github/coderabbit-config/check_coderabbit_config.py new file mode 100644 index 00000000..681ecfbd --- /dev/null +++ b/.github/coderabbit-config/check_coderabbit_config.py @@ -0,0 +1,642 @@ +#!/usr/bin/env python3 +"""Validate a repo's `.coderabbit.yaml` against CodeRabbit's config schema. + +Why this exists. CodeRabbit rejects an invalid `.coderabbit.yaml` **whole**: the +entire file is discarded and the review runs on org-wide UI defaults instead, so +every reviewer instruction, path filter, path instruction and WIP-skip rule in it +goes silently inert. Nothing about the PR looks different — the file still reads +fine, only the validator sees the loss. + +Worse, the feedback is displaced by one PR. CodeRabbit validates the config on +the BASE branch, not the PR head, so the PR that breaks the file goes green and +the breakage first surfaces on the *next* PR, attributed to a change that did not +cause it. Nobody is looking at the right diff when the signal finally arrives. +That is what makes this a machine check rather than a convention: the human +feedback loop is not merely slow here, it points at the wrong commit. + +Severity is split, and the split mirrors what CodeRabbit itself does with each +class of problem rather than what a schema library calls "invalid": + + * a YAML parse error, a `maxLength` violation, a type/enum error -> FAIL. + These are what CodeRabbit rejects the whole file for. + * an unknown / additional property -> WARN. + CodeRabbit STRIPS a key it does not recognize rather than rejecting the + file, so the config still loads — but everything under that key silently + does nothing. That is a real defect (a `tools:` block written at the root + instead of under `reviews:` inverts the settings it was meant to apply), + just not a file-rejecting one. `--strict-unknown-keys` escalates it to a + failure for a repo that has cleaned up and wants to stay clean. + +A repo with no `.coderabbit.yaml` passes, and says so in the log — not every +consumer of the reusable workflow has one. + +Validation is against a VENDORED copy of the schema committed beside this file, +never a live fetch: a network fetch on the validation path makes every consumer's +CI depend on a third-party endpoint, and an upstream tightening would turn CI red +across the fleet with no change on our side. `refresh-coderabbit-schema.yml` +watches upstream for drift and proposes the bump as a reviewable PR instead. + +Run locally: + python3 .github/coderabbit-config/check_coderabbit_config.py --root . +""" + +import argparse +import hashlib +import json +import os +import re +import sys +from itertools import islice + +try: + import yaml +except ImportError: # pragma: no cover - exercised only on a bare interpreter + print( + "::error::coderabbit-config: PyYAML is not installed. Install the pinned " + "requirements beside this script " + "(pip install --require-hashes -r .github/coderabbit-config/requirements.txt)." + ) + sys.exit(2) + +try: + from jsonschema import Draft202012Validator +except ImportError: # pragma: no cover - exercised only on a bare interpreter + print( + "::error::coderabbit-config: jsonschema is not installed. Install the pinned " + "requirements beside this script " + "(pip install --require-hashes -r .github/coderabbit-config/requirements.txt)." + ) + sys.exit(2) + +DEFAULT_CONFIG = ".coderabbit.yaml" +DEFAULT_SCHEMA = os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema.v2.json") + +# CodeRabbit honours both spellings of the extension, so a repo on the other one +# must not read as "no config here". See `_sibling_spelling`. +_SPELLING_SWAP = {".yaml": ".yml", ".yml": ".yaml"} + +# The config is PR-controlled, so both the input and the output are bounded. +# +# 512 KiB is ~two orders of magnitude above any real `.coderabbit.yaml`; the cap +# exists to stop a runner reading and parsing a junk file, not to police style. +# It is NOT a defence against alias amplification — a billion-laughs document is +# a few hundred bytes, and while PyYAML itself constructs each anchor once, +# `iter_errors` walks the resulting DAG as a tree. That is what MAX_FINDINGS and +# the caller's job timeout bound; the check fails closed either way. +MAX_CONFIG_BYTES = 512 * 1024 +MAX_FINDINGS = 100 + +# Keywords whose violation CodeRabbit tolerates by STRIPPING the offending key, +# rather than rejecting the document. Everything else is file-rejecting. +STRIPPED_KEYWORDS = frozenset({"additionalProperties", "unevaluatedProperties"}) + +# Guards the "did you mean" suggestion below: an unknown key is only worth +# proposing a home for when the name is specific enough that a same-named +# property elsewhere in the schema is likely the intended one. +_SUGGESTABLE_KEY_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]{2,}$") + + +class ConfigError(Exception): + """A problem with how the checker was invoked, not with the config.""" + + +def _esc_cmd(text): + """Escape a value before it is interpolated into a workflow-command line. + + Every string here — key names, YAML error text, the offending value's length + — is derived from a file the PR author controls, and YAML permits a newline + inside a quoted key. Unescaped, a key named "x\\n::stop-commands::tok" would + close this line and emit a SECOND, attacker-chosen workflow command, + suppressing the annotations printed after it or forging notices in a public + run log. Applied to the plain line too, since that line would equally start + a `::` command. Same helper, same reasoning, as check_agents_md.py. + """ + return str(text).replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A") + + +def _esc_prop(text): + """Escape a value used as an annotation PROPERTY (`file=`, `title=`). + + Properties are comma-separated and colon-terminated, so they need `,` and `:` + escaped on top of the message escaping — an unescaped comma in a path would + be read as the start of the next property. + """ + return _esc_cmd(text).replace(":", "%3A").replace(",", "%2C") + + +def _format_path(path_parts): + """Render a JSON-pointer-ish path as `reviews.path_instructions[0].path`.""" + if not path_parts: + return "(document root)" + out = "" + for part in path_parts: + if isinstance(part, int): + out += f"[{part}]" + else: + out += f".{part}" if out else str(part) + return out + + +def _index_schema_paths(schema): + """Map every property NAME in the schema to the dotted paths it appears at. + + Used only for the "did you mean" hint on an unknown key: a `tools:` block at + the document root is almost always `reviews.tools` written one level too + high, and naming the right home is the difference between a warning someone + acts on and one they scroll past. + """ + index = {} + + def walk(node, path): + if not isinstance(node, dict): + return + for name, sub in (node.get("properties") or {}).items(): + child = f"{path}.{name}" if path else name + index.setdefault(name, []).append(child) + walk(sub, child) + items = node.get("items") + if isinstance(items, dict): + walk(items, f"{path}[]") + + walk(schema, "") + return index + + +def _suggest_home(key, schema_index, offending_path): + """A one-line 'did you mean' for an unknown key, or '' when there is none.""" + if not isinstance(key, str) or not _SUGGESTABLE_KEY_RE.match(key): + return "" + candidates = [p for p in schema_index.get(key, []) if p != offending_path] + if not candidates: + return "" + shown = ", ".join(f"`{c}`" for c in sorted(candidates)[:3]) + return f" Did you mean {shown}?" + + +def _extra_keys(error): + """The property names an `additionalProperties: false` error actually rejected. + + jsonschema puts them in the human message only, so recompute them from the + instance and the subschema. That is what lets each unknown key be reported on + its own line, at its own path, with its own YAML line number — rather than + one blob naming the parent object. + """ + subschema = error.schema if isinstance(error.schema, dict) else {} + known = set(subschema.get("properties") or {}) + patterns = [] + for raw in subschema.get("patternProperties") or {}: + try: + patterns.append(re.compile(raw)) + except re.error: + continue + if not isinstance(error.instance, dict): + return [] + return [ + k + for k in error.instance + if k not in known and not any(p.search(str(k)) for p in patterns) + ] + + +def _line_for_path(node, path_parts): + """1-based YAML line of the value at `path_parts`, or None. + + Walks the composed node tree (`yaml.compose`), which carries source markers + PyYAML's plain `safe_load` throws away. A path the tree cannot follow — a + merge key, an alias, a shape the schema and the document disagree about — + returns None and the caller falls back to a file-level annotation, which is + strictly better than pointing at a confidently wrong line. + """ + current = node + for part in path_parts: + if current is None: + return None + current = _descend(current, part) + if current is None: + return None + return current.start_mark.line + 1 + + +def _key_line(node, parent_parts, key): + """1-based YAML line of the KEY `key` inside the mapping at `parent_parts`. + + An unknown key has no value the schema knows about, so the useful annotation + points at the key itself. + """ + parent = node + for part in parent_parts: + parent = _descend(parent, part) + if parent is None: + return None + if not isinstance(parent, yaml.MappingNode): + return None + for key_node, _ in parent.value: + if getattr(key_node, "value", None) == key: + return key_node.start_mark.line + 1 + return None + + +def _descend(node, part): + if isinstance(part, int): + if not isinstance(node, yaml.SequenceNode) or part >= len(node.value): + return None + return node.value[part] + if not isinstance(node, yaml.MappingNode): + return None + for key_node, value_node in node.value: + if getattr(key_node, "value", None) == part: + return value_node + return None + + +def _describe(error, path_str): + """A human sentence for one file-rejecting schema error.""" + if error.validator == "maxLength": + actual = len(error.instance) if isinstance(error.instance, str) else "?" + return ( + f"`{path_str}` is {actual} characters; the schema caps it at " + f"{error.validator_value}. CodeRabbit rejects the WHOLE config when a " + f"field is over its cap, falling back to org-wide UI defaults." + ) + if error.validator == "type": + got = type(error.instance).__name__ + want = error.validator_value + if isinstance(want, list): + want = " or ".join(str(w) for w in want) + return f"`{path_str}` must be {want}, got {got} ({error.instance!r})." + if error.validator == "enum": + return ( + f"`{path_str}`: {error.instance!r} is not one of the permitted values " + f"({', '.join(repr(v) for v in error.validator_value)})." + ) + if error.validator == "required": + return f"`{path_str}`: {error.message}" + return f"`{path_str}`: {error.message}" + + +def validate(text, schema, strict_unknown_keys=False): + """Validate one config document. + + Returns (findings, notes). A finding is + (severity, path, line_or_None, message) with severity in {"error","warning"}; + notes are informational log lines. Raises nothing for a bad config — a YAML + parse error comes back as a finding, because the caller wants an annotation, + not a traceback. + """ + findings = [] + notes = [] + + try: + data = yaml.safe_load(text) + except yaml.YAMLError as exc: + line = None + mark = getattr(exc, "problem_mark", None) + if mark is not None: + line = mark.line + 1 + # `str(exc)` on a MarkedYAMLError already embeds the marks, so this is + # the whole diagnosis in one line. + return ( + [("error", "(document)", line, f"not valid YAML: {exc}")], + notes, + ) + + if data is None: + notes.append( + "the file parsed to an empty document (blank, or comments only) — " + "nothing to validate" + ) + return findings, notes + + # Composed separately from safe_load: compose() keeps the source markers that + # turn a schema path into a clickable line, and a document safe_load accepted + # cannot fail here. + try: + node = yaml.compose(text) + except yaml.YAMLError: # pragma: no cover - unreachable after a clean load + node = None + + schema_index = _index_schema_paths(schema) + validator = Draft202012Validator(schema) + unknown_severity = "error" if strict_unknown_keys else "warning" + + # Sorted so annotations come out in document order. The key TAGS each part + # by kind rather than comparing raw values: `absolute_path` mixes string keys + # with integer indices, and comparing two such paths directly raises + # TypeError the moment an int meets a str at the same depth. + def _order(error): + return tuple( + (0, part, "") if isinstance(part, int) else (1, 0, str(part)) + for part in error.absolute_path + ) + + # Collected through `islice` rather than materialized whole: the document is + # PR-controlled, and a deeply aliased one can yield findings faster than any + # reviewer will read them (and flood a public run log doing it). One past the + # cap so the truncation can say so honestly. + raw_errors = list(islice(validator.iter_errors(data), MAX_FINDINGS + 1)) + truncated = len(raw_errors) > MAX_FINDINGS + del raw_errors[MAX_FINDINGS:] + + for error in sorted(raw_errors, key=_order): + parent_parts = list(error.absolute_path) + if error.validator in STRIPPED_KEYWORDS: + extras = _extra_keys(error) + if not extras: + # The subschema shape defeated the recomputation; report the + # library's own message rather than dropping the finding. + findings.append( + ( + unknown_severity, + _format_path(parent_parts), + _line_for_path(node, parent_parts), + error.message, + ) + ) + continue + for key in extras: + full = _format_path(parent_parts + [key]) + where = ( + "at the document root" + if not parent_parts + else f"under `{_format_path(parent_parts)}`" + ) + findings.append( + ( + unknown_severity, + full, + _key_line(node, parent_parts, key), + f"unknown key `{key}` {where}. CodeRabbit STRIPS keys it " + f"does not recognize, so the config still loads but " + f"everything under this key silently does nothing." + + _suggest_home(key, schema_index, full), + ) + ) + continue + + path_str = _format_path(parent_parts) + findings.append( + ("error", path_str, _line_for_path(node, parent_parts), _describe(error, path_str)) + ) + + if truncated: + notes.append( + f"more than {MAX_FINDINGS} schema violations in this file — only the " + f"first {MAX_FINDINGS} are reported. Fix these and re-run." + ) + + return findings, notes + + +def load_schema(path): + try: + with open(path, "r", encoding="utf-8") as f: + raw = f.read() + except OSError as exc: + raise ConfigError(f"cannot read the vendored schema at {path}: {exc}") + try: + schema = json.loads(raw) + except json.JSONDecodeError as exc: + raise ConfigError(f"the vendored schema at {path} is not valid JSON: {exc}") + if not isinstance(schema, dict) or "properties" not in schema: + # The failure mode this catches is concrete: the schema URL 301-redirects, + # and a `curl` without `-L` writes a 167-byte HTML redirect stub that is + # neither JSON nor a schema. A stub that somehow parsed would validate + # everything, i.e. gate nothing. + raise ConfigError( + f"the vendored schema at {path} is not a JSON Schema object with " + f"`properties` — refusing to validate against it (a check that " + f"cannot fail is worse than no check)." + ) + return schema, hashlib.sha256(raw.encode("utf-8")).hexdigest() + + +def _emit(findings, notes, config_rel): + """Print human lines plus GitHub annotations; return the exit code.""" + for note in notes: + note = _esc_cmd(note) + print(f"NOTE: {note}") + print(f"::notice::coderabbit-config: {note}") + + errors = [f for f in findings if f[0] == "error"] + warnings = [f for f in findings if f[0] == "warning"] + + for severity, _path, line, message in findings: + message = _esc_cmd(message) + label = "FAIL" if severity == "error" else "WARN" + where = f"{config_rel}:{line}" if line else config_rel + print(f"{label}: {_esc_cmd(where)} {message}") + props = f"file={_esc_prop(config_rel)}" + if line: + props += f",line={line}" + print(f"::{severity} {props}::coderabbit-config: {message}") + + if errors: + print( + f"\nResult: {len(errors)} error(s), {len(warnings)} warning(s) — " + f"{_esc_cmd(config_rel)} is invalid." + ) + return 1 + if warnings: + print(f"\nResult: passed with {len(warnings)} warning(s).") + else: + print("\nResult: .coderabbit.yaml OK.") + return 0 + + +def _contained(root_abs, path): + """Is `path` inside `root_abs` once symlinks on BOTH sides are resolved? + + `os.path.abspath` normalizes `..` textually but does NOT resolve symlinks, + while `os.path.isfile` and `open` below both follow them — so a + `.coderabbit.yaml` committed as a symlink to a path outside the checkout + would clear a purely textual guard and be read anyway. Its content can then + reach a PUBLIC run log: a `MarkedYAMLError` embeds the offending source line, + and `_describe`'s type branch prints the instance in full. Resolving the root + too is what keeps a legitimately symlinked checkout path (`/var` → `/private/var` + on macOS, and how CI temp dirs are handed out) from failing every config for + sitting "outside" a root that is itself a symlink. + """ + try: + return os.path.commonpath([root_abs, os.path.realpath(path)]) == root_abs + except ValueError: + # Different drives, or a mix of absolute and relative — not comparable, + # and therefore not containable either. + return False + + +def _sibling_spelling(root, config_rel): + """The other extension CodeRabbit also honours, when THAT file is the present one. + + CodeRabbit reads `.coderabbit.yaml` and `.coderabbit.yml` alike. A repo on the + `.yml` spelling that leaves `config_file` at its default would otherwise get a + permanently green "absent — pass" over a config that is real, in effect, and + possibly invalid — the same "checked nothing" failure the empty-path guard + returns 2 for, only quieter, because it looks exactly like a pass. + """ + stem, ext = os.path.splitext(config_rel) + other_ext = _SPELLING_SWAP.get(ext.lower()) + if not other_ext: + return None + other_rel = stem + other_ext + if os.path.isfile(os.path.join(root, other_rel)): + return other_rel + return None + + +def _env_bool(name, default): + raw = os.environ.get(name) + if raw is None or raw == "": + return default + return raw.strip().lower() in ("1", "true", "yes", "on") + + +def main(argv=None): + parser = argparse.ArgumentParser( + description="Validate .coderabbit.yaml against CodeRabbit's config schema." + ) + parser.add_argument( + "--root", + default=os.environ.get("CODERABBIT_CHECK_ROOT", "."), + help="Repo root to check (default: current directory).", + ) + parser.add_argument( + "--config", + default=os.environ.get("CODERABBIT_CONFIG_FILE") or DEFAULT_CONFIG, + help=f"Config path relative to --root (default: {DEFAULT_CONFIG}).", + ) + parser.add_argument( + "--schema", + default=os.environ.get("CODERABBIT_SCHEMA_FILE") or DEFAULT_SCHEMA, + help="Vendored JSON Schema to validate against (default: beside this script).", + ) + parser.add_argument( + "--strict-unknown-keys", + action="store_true", + default=_env_bool("STRICT_UNKNOWN_KEYS", False), + help=( + "Escalate an unknown/additional property from a warning to a " + "failure. Off by default because CodeRabbit strips such keys rather " + "than rejecting the file." + ), + ) + args = parser.parse_args(argv) + + config_rel = args.config + if not config_rel.strip(): + # An empty `config_file:` input would otherwise join to the repo root, + # fail the isfile() test, and report a clean pass over a repo whose + # config was never looked at — a green check that checked nothing. + msg = "config path is empty — pass a path relative to the repo root" + print(f"FAIL: {msg}") + print(f"::error::coderabbit-config: {msg}") + return 2 + config_path = os.path.join(args.root, config_rel) + + # Keep the validated file inside the tree we were pointed at. `config_file` + # reaches here from a workflow input, and `os.path.join` silently DISCARDS + # --root when handed an absolute path — so without this, `config_file: /etc/…` + # or `../../x` would read outside the caller's checkout and report on it. A + # symlink counts as outside too — see `_contained`. + root_abs = os.path.realpath(args.root) + if not _contained(root_abs, config_path): + msg = ( + f"config path '{config_rel}' resolves outside the checked-out repo " + f"root — refusing to read it. Give a path relative to the repo root " + f"(a symlink whose target leaves the tree resolves outside it too)." + ) + print(f"FAIL: {_esc_cmd(msg)}") + print(f"::error::coderabbit-config: {_esc_cmd(msg)}") + return 2 + + # Which file are we actually about to read? Three different states hide + # behind a false `isfile()`, and only one of them is "this repo has no + # config". Settle that BEFORE the banner below, so the banner names the file + # that really gets validated rather than the one that was asked for. + pending = [] + if os.path.lexists(config_path) and not os.path.isfile(config_path): + # A directory, or a symlink with no target. We were pointed at something + # unusable: that is a could-not-run, not a pass. + msg = ( + f"'{config_rel}' exists but is not a regular file (a directory, or a " + f"symlink with no target) — refusing to report a pass over it." + ) + print(f"FAIL: {_esc_cmd(msg)}") + print(f"::error::coderabbit-config: {_esc_cmd(msg)}") + return 2 + + absent = not os.path.isfile(config_path) + if absent: + sibling = _sibling_spelling(args.root, config_rel) + if sibling and _contained(root_abs, os.path.join(args.root, sibling)): + pending.append( + ( + "warning", + f"no {config_rel} in this repo, but {sibling} is — CodeRabbit " + f"honours both spellings, so {sibling} is the config in " + f"effect and is what was validated. Set `config_file: " + f"{sibling}` to make that explicit.", + ) + ) + config_rel = sibling + config_path = os.path.join(args.root, sibling) + absent = False + + try: + schema, schema_digest = load_schema(args.schema) + except ConfigError as exc: + msg = _esc_cmd(exc) + print(f"FAIL: {msg}") + print(f"::error::coderabbit-config: {msg}") + return 2 + + # Escaped like every other print in this file: `config_file` and `root` both + # arrive from `workflow_call` inputs a PR to the caller repo can edit, and a + # newline in either would emit an attacker-chosen second workflow command — + # `::stop-commands::` here suppresses every `::error::` annotation printed + # afterwards, so a failing check would silently lose its annotations. + print( + f"Validating '{_esc_cmd(config_rel)}' in '{_esc_cmd(args.root)}' against " + f"vendored schema {_esc_cmd(os.path.basename(args.schema))} " + f"(sha256 {schema_digest[:12]})..." + ) + print( + "Unknown keys: " + + ("FAIL (strict_unknown_keys)" if args.strict_unknown_keys else "warn only") + ) + print() + + for severity, line in pending: + label = "WARN" if severity == "warning" else "NOTE" + print(f"{label}: {_esc_cmd(line)}") + print(f"::{severity}::coderabbit-config: {_esc_cmd(line)}") + + if absent: + # Not every consumer repo has one, and a missing file is not a defect — + # but it IS reported, so "no config here" never looks the same in a log + # as "config validated clean". + line = f"no {config_rel} in this repo — nothing to validate" + print(f"NOTE: {_esc_cmd(line)}") + print(f"::notice::coderabbit-config: {_esc_cmd(line)}") + print("\nResult: .coderabbit.yaml absent — pass.") + return 0 + + size = os.path.getsize(config_path) + if size > MAX_CONFIG_BYTES: + msg = ( + f"'{config_rel}' is {size} bytes, past the {MAX_CONFIG_BYTES}-byte " + f"limit this checker will parse — refusing to read it. A real " + f"CodeRabbit config is kilobytes; this is not one." + ) + print(f"FAIL: {_esc_cmd(msg)}") + print(f"::error::coderabbit-config: {_esc_cmd(msg)}") + return 2 + + with open(config_path, "r", encoding="utf-8", errors="replace") as f: + text = f.read() + + findings, notes = validate(text, schema, strict_unknown_keys=args.strict_unknown_keys) + return _emit(findings, notes, config_rel) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/coderabbit-config/requirements.txt b/.github/coderabbit-config/requirements.txt new file mode 100644 index 00000000..49faed4c --- /dev/null +++ b/.github/coderabbit-config/requirements.txt @@ -0,0 +1,53 @@ +# Pinned dependencies for the .coderabbit.yaml validator. +# +# This repo is otherwise stdlib-only, on purpose (see AGENTS.md). Two things +# make this checker the exception, and neither has a stdlib answer: +# +# * PyYAML — the input is YAML. There is no YAML parser in the standard +# library, and hand-rolling one to gate 15 repos' CI would trade a real +# parser for a novel source of false failures. +# * jsonschema — the point of the check is to reproduce the verdict CodeRabbit +# itself reaches against its published Draft 2020-12 schema. A hand-written +# subset validator would agree with the real one until it didn't, and the +# day it diverged the check would either gate nothing or fail a valid config. +# +# So the dependency is accepted and PINNED HARD instead: exact versions with +# sha256 hashes, installed with `--require-hashes`, which makes pip refuse any +# artifact whose bytes differ from the ones reviewed here. That matches the rest +# of the repo's supply-chain posture (SHA-pinned actions, a sha256-pinned Cursor +# CLI) rather than departing from it. +# +# The wheels are the cp312 / manylinux x86_64 ones, matching the `ubuntu-latest` +# + `python-version: '3.12'` pair every consuming job pins. A runner that is not +# that pair fails the install LOUDLY, which is the correct direction: a silent +# fallback to an unhashed artifact is the thing --require-hashes exists to stop. +# +# Dependabot watches this file (see .github/dependabot.yml, `pip` ecosystem) and +# regenerates the hashes on a bump, so the pins do not rot the way an unwatched +# inline `pip install x==1.2.3` does. +# +# Regenerate by hand with: +# pip download --only-binary=:all: --platform manylinux2014_x86_64 \ +# --python-version 3.12 --implementation cp --abi cp312 -d /tmp/wheels \ +# 'jsonschema==' 'PyYAML==' && pip hash /tmp/wheels/*.whl + +jsonschema==4.25.1 \ + --hash=sha256:3fba0169e345c7175110351d456342c364814cfcf3b964ba4587f22915230a63 +PyYAML==6.0.3 \ + --hash=sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc + +# Transitive dependencies of jsonschema, pinned for the same reason. +attrs==26.1.0 \ + --hash=sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309 +jsonschema-specifications==2025.9.1 \ + --hash=sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe +referencing==0.37.0 \ + --hash=sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231 +rpds-py==2026.6.3 \ + --hash=sha256:ecabd69db66de867690f9797f2f8fa27ba501bbc24540cbdbdc649cd15888ba6 +# `referencing` requires this on Python < 3.13, which the pinned 3.12 is. It is +# easy to leave out — a resolution run on a 3.13+ interpreter drops it from the +# set — and leaving it out breaks the install only on the runner, so it is listed +# explicitly rather than trusted to a resolver's environment. +typing-extensions==4.16.0 \ + --hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 diff --git a/.github/coderabbit-config/schema.v2.json b/.github/coderabbit-config/schema.v2.json new file mode 100644 index 00000000..86df6e58 --- /dev/null +++ b/.github/coderabbit-config/schema.v2.json @@ -0,0 +1,2249 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "language": { + "default": "en-US", + "description": "Set the language for reviews by using the corresponding ISO language code.", + "type": "string", + "enum": [ + "de", + "de-DE", + "de-AT", + "de-CH", + "en", + "en-US", + "en-AU", + "en-GB", + "en-CA", + "en-NZ", + "en-ZA", + "es", + "es-AR", + "fr", + "fr-CA", + "fr-CH", + "fr-BE", + "nl", + "nl-BE", + "pt-AO", + "pt", + "pt-BR", + "pt-MZ", + "pt-PT", + "ar", + "ast-ES", + "ast", + "be-BY", + "be", + "br-FR", + "br", + "ca-ES", + "ca", + "ca-ES-valencia", + "ca-ES-balear", + "da-DK", + "da", + "de-DE-x-simple-language", + "el-GR", + "el", + "eo", + "fa", + "ga-IE", + "ga", + "gl-ES", + "gl", + "it", + "ja-JP", + "ja", + "km-KH", + "km", + "ko-KR", + "ko", + "pl-PL", + "pl", + "ro-RO", + "ro", + "ru-RU", + "ru", + "sk-SK", + "sk", + "sl-SI", + "sl", + "sv", + "ta-IN", + "ta", + "tl-PH", + "tl", + "tr", + "uk-UA", + "uk", + "zh-CN", + "zh", + "zh-TW", + "crh-UA", + "crh", + "cs-CZ", + "cs", + "nb", + "no", + "nl-NL", + "de-DE-x-simple-language-DE", + "es-ES", + "it-IT", + "fa-IR", + "sv-SE", + "de-LU", + "fr-FR", + "bg-BG", + "bg", + "he-IL", + "he", + "hi-IN", + "hi", + "vi-VN", + "vi", + "th-TH", + "th", + "bn-BD", + "bn" + ], + "enumNames": [ + "German", + "German (Germany)", + "German (Austria)", + "German (Swiss)", + "English", + "English (US)", + "English (Australian)", + "English (GB)", + "English (Canadian)", + "English (New Zealand)", + "English (South African)", + "Spanish", + "Spanish (voseo)", + "French", + "French (Canada)", + "French (Switzerland)", + "French (Belgium)", + "Dutch", + "Dutch (Belgium)", + "Portuguese (Angola preAO)", + "Portuguese", + "Portuguese (Brazil)", + "Portuguese (Moçambique preAO)", + "Portuguese (Portugal)", + "Arabic", + "Asturian", + "Asturian", + "Belarusian", + "Belarusian", + "Breton", + "Breton", + "Catalan", + "Catalan", + "Catalan (Valencian)", + "Catalan (Balearic)", + "Danish", + "Danish", + "Simple German", + "Greek", + "Greek", + "Esperanto", + "Persian", + "Irish", + "Irish", + "Galician", + "Galician", + "Italian", + "Japanese", + "Japanese", + "Khmer", + "Khmer", + "Korean", + "Korean", + "Polish", + "Polish", + "Romanian", + "Romanian", + "Russian", + "Russian", + "Slovak", + "Slovak", + "Slovenian", + "Slovenian", + "Swedish", + "Tamil", + "Tamil", + "Tagalog", + "Tagalog", + "Turkish", + "Ukrainian", + "Ukrainian", + "Simplified Chinese", + "Simplified Chinese", + "Traditional Chinese", + "Crimean Tatar", + "Crimean Tatar", + "Czech", + "Czech", + "Norwegian", + "Norwegian (Bokmål)", + "Dutch (Netherlands)", + "Simple German", + "Spanish", + "Italian", + "Persian", + "Swedish", + "German (Luxembourg)", + "French", + "Bulgarian", + "Bulgarian", + "Hebrew", + "Hebrew", + "Hindi", + "Hindi", + "Vietnamese", + "Vietnamese", + "Thai", + "Thai", + "Bengali", + "Bengali" + ] + }, + "tone_instructions": { + "default": "", + "description": "Set the tone of reviews and chat. Example: 'You must talk like Mr. T. I pity the fool who doesn't!'", + "type": "string", + "maxLength": 250 + }, + "early_access": { + "default": false, + "description": "Enable early-access features.", + "type": "boolean" + }, + "enable_free_tier": { + "default": true, + "description": "Enable free tier features for users not on a paid plan.", + "type": "boolean" + }, + "inheritance": { + "default": false, + "description": "Inheritance | Use parent settings for any values not defined here. Inheritance only propagates upward if enabled at each level.", + "type": "boolean" + }, + "reviews": { + "default": {}, + "description": "Settings related to reviews.", + "type": "object", + "properties": { + "profile": { + "default": "chill", + "description": "Set the review profile: quiet for only the most important feedback, chill for balanced feedback, assertive for more feedback (which may feel nitpicky).", + "type": "string", + "enum": ["quiet", "chill", "assertive"] + }, + "request_changes_workflow": { + "default": false, + "description": "Automatically approve once CodeRabbit’s comments are resolved and no pre-merge checks are failing. Note: In GitLab, all discussions must be resolved.", + "type": "boolean" + }, + "high_level_summary": { + "default": true, + "description": "Generate a high-level summary of the changes in the PR description or walkthrough.", + "type": "boolean" + }, + "high_level_summary_instructions": { + "default": "", + "description": "By default, CodeRabbit generates release notes in the description. Use this to customize the summary content and format. Example: 'Create concise release notes as a bullet-point list, followed by a Markdown table showing lines added and removed by each contributing author.' Note: Use `high_level_summary_in_walkthrough` to place the summary in the walkthrough instead of the description.", + "type": "string" + }, + "high_level_summary_placeholder": { + "default": "@coderabbitai summary", + "description": "Placeholder in the PR description that CodeRabbit replaces with the high-level summary. If `high_level_summary` is false, the summary is still generated when this placeholder is present.", + "type": "string" + }, + "high_level_summary_in_walkthrough": { + "default": false, + "description": "Include the high-level summary in the walkthrough comment.", + "type": "boolean" + }, + "auto_title_placeholder": { + "default": "@coderabbitai", + "description": "Add this keyword to the PR title to auto-generate a title.", + "type": "string" + }, + "auto_title_instructions": { + "default": "", + "description": "Auto Title Instructions | Customize how CodeRabbit generates the PR title.", + "type": "string" + }, + "review_status": { + "default": true, + "description": "Post review status messages (e.g., when a review is skipped) in the walkthrough summary comment.", + "type": "boolean" + }, + "review_details": { + "default": false, + "description": "Post review details (ignored files, extra context used, suppressed comments, etc.).", + "type": "boolean" + }, + "review_progress": { + "default": true, + "description": "Publish the canonical user-facing review status and progress updates (GitHub progress reports/check runs today; other platform equivalents may follow).", + "type": "boolean" + }, + "commit_status": { + "default": true, + "description": "Mirror review progress using legacy commit statuses for compatibility with required checks and existing automations. This setting is only used when review_progress is disabled.", + "type": "boolean" + }, + "fail_commit_status": { + "default": false, + "description": "On review errors, fail the active outward review status surface. When review_progress is enabled this applies to progress reporting; otherwise it applies to the legacy commit-status mirror when enabled.", + "type": "boolean" + }, + "collapse_walkthrough": { + "default": true, + "description": "Wrap the walkthrough in a Markdown collapsible section.", + "type": "boolean" + }, + "changed_files_summary": { + "default": true, + "description": "Include a summary of the changed files in the walkthrough.", + "type": "boolean" + }, + "sequence_diagrams": { + "default": true, + "description": "Include sequence diagrams in the walkthrough.", + "type": "boolean" + }, + "estimate_code_review_effort": { + "default": true, + "description": "Include an estimated code review effort in the walkthrough.", + "type": "boolean" + }, + "assess_linked_issues": { + "default": true, + "description": "Include an assessment of how well the changes address linked issues in the walkthrough.", + "type": "boolean" + }, + "related_issues": { + "default": true, + "description": "Include potentially related issues in the walkthrough.", + "type": "boolean" + }, + "related_prs": { + "default": true, + "description": "Related PRs | Include potentially related PRs in the walkthrough.", + "type": "boolean" + }, + "suggested_labels": { + "default": true, + "description": "Suggest labels based on the changes, and include them in the walkthrough.", + "type": "boolean" + }, + "labeling_instructions": { + "default": [], + "description": "Labeling Instructions | Define allowed labels and when to suggest them. When provided, CodeRabbit suggests only from this list (still informed by prior PRs); when empty, suggestions rely entirely on prior PRs.", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Label to suggest for the PR. Example: frontend" + }, + "instructions": { + "type": "string", + "maxLength": 3000, + "description": "Instructions for the label. Example: Apply when the PR contains changes to React components." + } + }, + "required": ["label", "instructions"] + } + }, + "mutually_exclusive_groups": { + "default": {}, + "description": "Mutually Exclusive Groups | Define labels that should not coexist. Example: `{ risk: ['critical', 'high', 'medium', 'low'] }`.", + "type": "object", + "propertyNames": { + "type": "string", + "minLength": 1 + }, + "additionalProperties": { + "minItems": 2, + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "auto_apply_labels": { + "default": false, + "description": "Automatically apply suggested labels to the PR.", + "type": "boolean" + }, + "suggested_reviewers": { + "default": true, + "description": "Suggest reviewers based on the changes, and include them in the walkthrough.", + "type": "boolean" + }, + "auto_assign_reviewers": { + "default": false, + "description": "Automatically assign the suggested reviewers to the PR.", + "type": "boolean" + }, + "suggested_reviewers_instructions": { + "default": [], + "description": "Reviewer Instructions | Map reviewers (users or team) to PR scenarios where they should be assigned. When empty, suggestions rely on prior PRs. Team handles are supported only on GitHub.", + "type": "array", + "items": { + "type": "object", + "properties": { + "reviewers": { + "minItems": 1, + "type": "array", + "items": { + "type": "object", + "properties": { + "handle": { + "type": "string", + "minLength": 1, + "description": "Reviewer username or team slug to assign. Example: security-pdl" + }, + "type": { + "default": "user", + "description": "Whether the reviewer is an individual user or a team/group.", + "type": "string", + "enum": ["user", "group"] + } + }, + "required": ["handle"] + }, + "description": "List of reviewers to assign when the PR matches the instructions below. Each entry pairs a handle (username or team slug) with its type (user or group)." + }, + "instructions": { + "type": "string", + "minLength": 1, + "maxLength": 3000, + "description": "Instructions for when to assign these reviewers. Example: Assign when the PR contains Windows registry changes." + } + }, + "required": ["reviewers", "instructions"] + } + }, + "in_progress_fortune": { + "default": true, + "description": "Post a fortune message while the review is running.", + "type": "boolean" + }, + "poem": { + "default": false, + "description": "Generate a poem in the walkthrough comment.", + "type": "boolean" + }, + "enable_prompt_for_ai_agents": { + "default": true, + "description": "Prompt for AI Agents | Include the '🤖 Prompt for AI Agents' section in inline review comments to provide codegen instructions for AI agents.", + "type": "boolean" + }, + "path_filters": { + "default": [], + "description": "Specify file patterns to include or exclude in a review using glob patterns (e.g., `!dist/**`, `src/**`). These patterns also apply to 'git sparse-checkout', including specified patterns and ignoring excluded ones (starting with '!') when cloning the repository.", + "type": "array", + "items": { + "type": "string" + } + }, + "path_instructions": { + "default": [], + "description": "Path Instructions | Add path-specific guidance for code review.", + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path glob pattern. Example: `**/*.js`." + }, + "instructions": { + "type": "string", + "maxLength": 20000, + "description": "Additional review guidance for matching paths." + } + }, + "required": ["path", "instructions"] + } + }, + "abort_on_close": { + "default": true, + "description": "Abort the in-progress review if the PR is closed or merged.", + "type": "boolean" + }, + "disable_cache": { + "default": false, + "description": "Disable caching of code and dependencies; fetch them fresh on each run.", + "type": "boolean" + }, + "slop_detection": { + "description": "Anti-Slop | Settings for detecting and managing spam or low-quality PRs. Only for public repos, only for GitHub as of now.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable or disable slop and low-quality PR detection.", + "type": "boolean" + }, + "label": { + "description": "Label to apply to the PR when it is classified as slop. Example: slop", + "type": "string", + "minLength": 1 + } + } + }, + "auto_review": { + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Automatic Review | Review PRs automatically.", + "type": "boolean" + }, + "description_keyword": { + "default": "", + "description": "Keyword in the PR description that triggers a review when automatic reviews are disabled. If `enabled` is false and this field is not empty, CodeRabbit reviews the PR only when this keyword is present in the description.", + "type": "string" + }, + "auto_incremental_review": { + "default": true, + "description": "Incremental Review | Re-run the review on each push.", + "type": "boolean" + }, + "auto_pause_after_reviewed_commits": { + "default": 5, + "description": "Auto Pause After Reviewed Commits | Pause automatic reviews after this many reviewed commits since the last pause. Set to 0 to disable.", + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "ignore_title_keywords": { + "default": [], + "description": "Skip reviews when the PR title contains any of these keywords (case-insensitive).", + "type": "array", + "items": { + "type": "string" + } + }, + "labels": { + "default": [], + "description": "Labels that control which PRs are reviewed. Labels starting with '!' are negative matches. Examples: ['bug', 'feature'] reviews PRs with either label. ['!wip'] reviews all PRs except those labeled 'wip' when automatic reviews are enabled. ['bug', '!wip'] reviews PRs labeled 'bug' but not 'wip'. When `enabled` is false, a positive label match (for example ['review-ready']) triggers a review; negative-only labels such as ['!wip'] remain exclusion filters and do not opt PRs in by themselves.", + "type": "array", + "items": { + "type": "string" + } + }, + "drafts": { + "default": false, + "description": "Include draft PRs.", + "type": "boolean" + }, + "base_branches": { + "default": [], + "description": "Base branches (other than the default branch) to review. Accepts regex patterns. Use '.*' to match all branches.", + "type": "array", + "items": { + "type": "string" + } + }, + "ignore_usernames": { + "default": [], + "description": "Skip reviews for PRs authored by these usernames (exact match; not email addresses).", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "finishing_touches": { + "default": {}, + "type": "object", + "properties": { + "docstrings": { + "description": "Docstrings | Configure docstring generation.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Docstrings | Enable the docstrings finishing touch (trigger via the 📝 Generate docstrings checkbox or `@coderabbitai generate docstrings`). CodeRabbit generates or improves docstrings for functions changed in the PR and opens a follow-up PR containing the docstring edits.", + "type": "boolean" + } + } + }, + "unit_tests": { + "description": "Unit Tests | Configure unit test generation.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Unit Tests | Generate unit tests for changes in PRs.", + "type": "boolean" + } + } + }, + "simplify": { + "description": "Simplify | Configure code simplification.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": false, + "description": "Simplify | Enable the simplify finishing touch (trigger via the ✨ Simplify code checkbox). CodeRabbit reviews changed code for reuse, quality, and efficiency, then applies targeted improvements.", + "type": "boolean" + } + } + }, + "autofix": { + "description": "Autofix | Configure autofix behavior.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Autofix | Enable the autofix finishing touch (trigger via the 🪄 Autofix checkboxes under review comments or the `@coderabbitai autofix` command). When disabled, the autofix checkboxes are hidden, the command is removed from help, and CodeRabbit declines `@coderabbitai autofix` requests.", + "type": "boolean" + } + } + }, + "fix_ci": { + "description": "Fix Failing CI | Configure the CI fixer.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Fix Failing CI | Enable the fix-ci finishing touch. When CI fails on a pull request, Finishing Touches offers mutually exclusive options to open a stacked pull request or commit fixes directly to the current branch. The `@coderabbitai fix-ci` command opens a stacked pull request by default; `@coderabbitai fix-ci commit` commits directly. When disabled, both commands are removed from help and CodeRabbit declines fix-ci requests. GitHub only; requires a Pro Plus plan.", + "type": "boolean" + } + } + }, + "resolve_merge_conflict": { + "description": "Resolve Merge Conflicts | Configure the merge-conflict resolver.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Resolve Merge Conflicts | Enable the merge-conflict resolver (trigger via `@coderabbitai resolve merge conflict`). CodeRabbit analyzes the intent behind both sides of a conflict and commits a resolution to your branch. When disabled, the command is removed from help and CodeRabbit declines resolution requests. Available on GitHub and GitLab; requires a Pro Plus plan.", + "type": "boolean" + } + } + }, + "custom": { + "default": [], + "description": "Custom Recipes | Define up to 5 custom finishing touch recipes. Trigger a recipe with `@coderabbitai run `.", + "maxItems": 5, + "type": "array", + "items": { + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enabled | Enable this custom finishing touch recipe.", + "type": "boolean" + }, + "name": { + "default": "", + "description": "Name | Recipe name used in commands (for example: `@coderabbitai run cleanup stale imports`). Run with `@coderabbitai run `.", + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "instructions": { + "default": "", + "description": "Instructions | Describe what this recipe should do. Trigger with `@coderabbitai run ` or the checkbox under \"✨ Finishing Touches\". CodeRabbit provides PR context and runs this with an agent.", + "type": "string", + "minLength": 1, + "maxLength": 10000 + } + } + } + } + } + }, + "pre_merge_checks": { + "default": {}, + "type": "object", + "properties": { + "override_requested_reviewers_only": { + "default": false, + "description": "Override Requested Reviewers Only | When enabled, only requested reviewers (and not the pull request author) can override/ignore failing pre-merge checks.", + "type": "boolean" + }, + "docstrings": { + "description": "Docstring Coverage | Check that docstring coverage meets the configured threshold.", + "default": {}, + "type": "object", + "properties": { + "mode": { + "default": "warning", + "description": "Mode | Enforcement level: `off` disables the check, `warning` posts a warning, and `error` requires resolution before merging. If the request-changes workflow is enabled, `error` can block the PR until the check passes.", + "type": "string", + "enum": ["off", "warning", "error"] + }, + "threshold": { + "default": 80, + "description": "Threshold | Minimum docstring coverage (%) required to pass.", + "type": "number", + "minimum": 0, + "maximum": 100 + } + } + }, + "title": { + "description": "Title Check | Validate the PR title against the requirements.", + "default": {}, + "type": "object", + "properties": { + "mode": { + "default": "warning", + "description": "Mode | Enforcement level: `off` disables the check, `warning` posts a warning, and `error` requires resolution before merging. If the request-changes workflow is enabled, `error` can block the PR until the check passes.", + "type": "string", + "enum": ["off", "warning", "error"] + }, + "requirements": { + "default": "", + "description": "Requirements | Describe title requirements. Example: 'Title should be concise and descriptive, ideally under 50 characters.'", + "type": "string" + } + } + }, + "description": { + "description": "Description Check | Check that the PR description follows best practices.", + "default": {}, + "type": "object", + "properties": { + "mode": { + "default": "warning", + "description": "Mode | Enforcement level: `off` disables the check, `warning` posts a warning, and `error` requires resolution before merging. If the request-changes workflow is enabled, `error` can block the PR until the check passes.", + "type": "string", + "enum": ["off", "warning", "error"] + } + } + }, + "issue_assessment": { + "description": "Linked Issue Assessment | Assess how well the PR addresses linked issues.", + "default": {}, + "type": "object", + "properties": { + "mode": { + "default": "warning", + "description": "Mode | Enforcement level: `off` disables the check, `warning` posts a warning, and `error` requires resolution before merging. If the request-changes workflow is enabled, `error` can block the PR until the check passes.", + "type": "string", + "enum": ["off", "warning", "error"] + } + } + }, + "custom_checks": { + "default": [], + "description": "Custom Pre-merge Checks | Define custom checks that must pass before merging. Each check needs a unique name (≤50 chars) and deterministic instructions (≤10,000 chars).", + "maxItems": 50, + "type": "array", + "items": { + "type": "object", + "properties": { + "mode": { + "default": "warning", + "description": "Mode | Enforcement level: `off` disables the check, `warning` posts a warning, and `error` requires resolution before merging. If the request-changes workflow is enabled, `error` can block the PR until the check passes.", + "type": "string", + "enum": ["off", "warning", "error"] + }, + "name": { + "default": "", + "description": "Name | Display name (max 50 characters).", + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + "instructions": { + "default": "", + "description": "Instructions | Deterministic pass/fail criteria (max 10,000 characters).", + "type": "string", + "minLength": 1, + "maxLength": 10000 + } + } + } + } + } + }, + "post_merge_actions": { + "default": [], + "description": "Custom Post-merge Actions | Define custom actions to run after merging. Each action needs a unique name (≤100 chars) and a deterministic prompt (≤10,000 chars).", + "maxItems": 5, + "type": "array", + "items": { + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enabled | Run this action after a PR is merged.", + "type": "boolean" + }, + "name": { + "default": "", + "description": "Name | Display name (max 100 characters).", + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "prompt": { + "default": "", + "description": "Prompt | Deterministic instructions describing the action to perform (max 10,000 characters).", + "type": "string", + "minLength": 1, + "maxLength": 10000 + } + } + } + }, + "tools": { + "default": {}, + "description": "Tools that provide additional context to code reviews.", + "type": "object", + "properties": { + "ast-grep": { + "description": "Enable ast-grep | ast-grep is a code analysis tool that helps you to find patterns in your codebase using abstract syntax trees patterns. | v0.45.1", + "default": {}, + "type": "object", + "properties": { + "rule_dirs": { + "default": [], + "description": "List of rules directories.", + "type": "array", + "items": { + "type": "string" + } + }, + "util_dirs": { + "default": [], + "description": "List of utils directories.", + "type": "array", + "items": { + "type": "string" + } + }, + "essential_rules": { + "default": true, + "description": "Use ast-grep essentials package.", + "type": "boolean" + }, + "packages": { + "default": [], + "description": "Predefined packages to be used.", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "shellcheck": { + "description": "ShellCheck is a static analysis tool that finds bugs in your shell scripts.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable ShellCheck | ShellCheck is a static analysis tool that finds bugs in your shell. | Enable ShellCheck integration. | v0.11.0", + "type": "boolean" + } + } + }, + "ruff": { + "description": "Ruff is a Python linter and code formatter.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Ruff | Ruff is a Python linter and code formatter. | Enable Ruff integration. | v0.16.1", + "type": "boolean" + } + } + }, + "markdownlint": { + "description": "markdownlint-cli2 is a static analysis tool to enforce standards and consistency for Markdown files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable markdownlint | markdownlint-cli2 is a static analysis tool to enforce standards and consistency for Markdown files. | Enable markdownlint integration. | v0.23.2", + "type": "boolean" + } + } + }, + "github-checks": { + "description": "GitHub Checks integration configuration.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable GitHub Checks\n\t\t\t| Enable integration, defaults to true\n\t\t\t| Enable GitHub Checks integration.", + "type": "boolean" + } + } + }, + "languagetool": { + "description": "LanguageTool is a style and grammar checker for 30+ languages.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable LanguageTool | Enable LanguageTool integration.", + "type": "boolean" + }, + "enabled_rules": { + "default": [], + "description": "IDs of rules to be enabled. The rule won't run unless 'level' is set to a level that activates the rule.", + "type": "array", + "items": { + "type": "string" + } + }, + "disabled_rules": { + "default": [], + "description": "IDs of rules to be disabled. Note: EN_UNPAIRED_BRACKETS, and EN_UNPAIRED_QUOTES are always disabled.", + "type": "array", + "items": { + "type": "string" + } + }, + "enabled_categories": { + "default": [], + "description": "IDs of categories to be enabled.", + "type": "array", + "items": { + "type": "string" + } + }, + "disabled_categories": { + "default": [], + "description": "IDs of categories to be disabled. Note: TYPOS, TYPOGRAPHY, and CASING are always disabled.", + "type": "array", + "items": { + "type": "string" + } + }, + "enabled_only": { + "default": false, + "description": "Only the rules and categories whose IDs are specified with 'enabledRules' or 'enabledCategories' are enabled.", + "type": "boolean" + }, + "level": { + "default": "default", + "description": "If set to 'picky', additional rules will be activated, i.e. rules that you might only find useful when checking formal text.", + "type": "string", + "enum": ["default", "picky"] + } + } + }, + "biome": { + "description": "Biome is a fast formatter, linter, and analyzer for web projects.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Biome | Biome is a fast formatter, linter, and analyzer for web projects. | Enable Biome integration. | v2.5.6", + "type": "boolean" + } + } + }, + "hadolint": { + "description": "Hadolint is a Dockerfile linter.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Hadolint | Hadolint is a Dockerfile linter. | Enable Hadolint integration. | v2.15.1", + "type": "boolean" + } + } + }, + "swiftlint": { + "description": "SwiftLint integration configuration object.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable SwiftLint | SwiftLint is a Swift linter. | Enable SwiftLint integration. | v0.65.0", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the SwiftLint configuration file relative to the repository. This is useful when the configuration file is named differently than the default '.swiftlint.yml' or '.swiftlint.yaml'.", + "type": "string" + } + } + }, + "phpstan": { + "description": "PHPStan is a tool to analyze PHP code.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable PHPStan | PHPStan requires [config file](https://phpstan.org/config-reference#config-file) in your repository root. Please ensure that this file contains the `paths:` parameter. | v2.2.7", + "type": "boolean" + }, + "level": { + "default": "default", + "description": "Level | Specify the [rule level](https://phpstan.org/user-guide/rule-levels) to run. When set to `default`, the level is determined by the review profile: `chill` uses level 3 (real bugs only — return/property type mismatches, array offset errors) and `assertive` uses level 8 (adds dead code detection, argument type checking, null safety, and typehint checks). This setting is ignored if your configuration file already has a `level:` parameter.", + "type": "string", + "enum": [ + "0", + "1", + "2", + "3", + "4", + "5", + "6", + "7", + "8", + "9", + "default", + "max" + ] + } + } + }, + "phpmd": { + "description": "PHPMD is a tool to find potential problems in PHP code.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable PHPMD | PHPMD is a tool to find potential problems in PHP code. | v2.15.0", + "type": "boolean" + } + } + }, + "phpcs": { + "description": "PHP CodeSniffer is a PHP linter and coding standard checker.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable PHP CodeSniffer | PHP CodeSniffer is a PHP linter and coding standard checker. | v3.13.6", + "type": "boolean" + } + } + }, + "golangci-lint": { + "description": "golangci-lint is a fast linters runner for Go.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable golangci-lint | golangci-lint is a fast linters runner for Go. | Enable golangci-lint integration. | v2.12.2", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the golangci-lint configuration file relative to the repository. Useful when the configuration file is named differently than the default '.golangci.yml', '.golangci.yaml', '.golangci.toml', '.golangci.json'.", + "type": "string" + } + } + }, + "yamllint": { + "description": "YAMLlint is a linter for YAML files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable YAMLlint | YAMLlint is a linter for YAML files. | Enable YAMLlint integration. | v1.37.1", + "type": "boolean" + } + } + }, + "gitleaks": { + "description": "Betterleaks is a secret scanner (an improved version of Gitleaks).", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Betterleaks | Betterleaks is a secret scanner (an improved version of Gitleaks). | Enable Betterleaks integration. | v1.7.3", + "type": "boolean" + } + } + }, + "trufflehog": { + "description": "TruffleHog is a secret scanner with verification capabilities that can detect and verify secrets in code.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable TruffleHog | TruffleHog is a secret scanner with verification capabilities. | Enable TruffleHog integration. | v3.96.0", + "type": "boolean" + } + } + }, + "checkov": { + "description": "Checkov is a static code analysis tool for infrastructure-as-code files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Checkov | Checkov is a static code analysis tool for infrastructure-as-code files. | v3.3.9", + "type": "boolean" + } + } + }, + "tflint": { + "description": "TFLint is a Terraform linter for finding potential errors and enforcing best practices.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable TFLint | TFLint is a Terraform linter for finding potential errors. | v0.64.0", + "type": "boolean" + } + } + }, + "detekt": { + "description": "Detekt is a static code analysis tool for Kotlin files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable detekt | detekt is a static code analysis tool for Kotlin files. | v1.23.8", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the detekt configuration file relative to the repository.", + "type": "string" + } + } + }, + "eslint": { + "description": "ESLint is a static code analysis tool for JavaScript files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable ESLint | ESLint is a static code analysis tool for JavaScript files.", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to an ESLint configuration file relative to the repository. When set, this configuration is used for every file instead of discovering ESLint configurations recursively.", + "type": "string" + }, + "e18e": { + "description": "@e18e/eslint-plugin modernization, performance, and dependency replacement checks.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable @e18e/eslint-plugin | Detects dependencies with modern replacements, flags unmaintained packages, and suggests native API alternatives or lighter replacements | v0.6.0", + "type": "boolean" + } + } + } + } + }, + "flake8": { + "description": "Flake8 is a Python linter that wraps PyFlakes, pycodestyle and Ned Batchelder's McCabe script.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Flake8 | Flake8 is a Python linter that wraps PyFlakes, pycodestyle and Ned Batchelder's McCabe script. | v7.3.0", + "type": "boolean" + } + } + }, + "fbinfer": { + "description": "Configuration for Infer to find bugs in Java and C/C++ code", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Infer for static bug analysis in Java and C/C++ code | v1.3.0", + "type": "boolean" + }, + "enable_java": { + "default": false, + "description": "Enable Java analysis | Disabled by default because Java analysis may require compiling more than the changed files.", + "type": "boolean" + } + } + }, + "fortitudeLint": { + "description": "Fortitude is a Fortran linter that checks for code quality and style issues.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Fortitude | Fortitude is a Fortran linter that checks for code quality and style issues | v0.9.2", + "type": "boolean" + } + } + }, + "rubocop": { + "description": "RuboCop is a Ruby static code analyzer (a.k.a. linter ) and code formatter.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable RuboCop | RuboCop is a Ruby static code analyzer (a.k.a. linter ) and code formatter. | v1.88.2", + "type": "boolean" + } + } + }, + "buf": { + "description": "Buf offers linting for Protobuf files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Buf | Buf offers linting for Protobuf files. | v1.72.0", + "type": "boolean" + } + } + }, + "regal": { + "description": "Regal is a linter and language server for Rego.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Regal | Regal is a linter and language server for Rego. | v0.42.0", + "type": "boolean" + } + } + }, + "actionlint": { + "description": "actionlint is a static checker for GitHub Actions workflow files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable actionlint | actionlint is a static checker for GitHub Actions workflow files. | v1.7.12", + "type": "boolean" + } + } + }, + "zizmor": { + "description": "zizmor is a static security analyzer for GitHub Actions workflow files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable zizmor | zizmor is a static security analyzer for GitHub Actions workflow files. | v1.29.0", + "type": "boolean" + } + } + }, + "pmd": { + "description": "PMD is an extensible multilanguage static code analyzer. It’s mainly concerned with Java.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable PMD | PMD is an extensible multilanguage static code analyzer. It’s mainly concerned with Java. | v7.26.0", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the PMD configuration file relative to the repository.", + "type": "string" + } + } + }, + "clang": { + "description": "Configuration for Clang to perform static analysis on C and C++ code", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Clang for C/C++ static analysis and code quality checks | v14.0.6", + "type": "boolean" + } + } + }, + "cppcheck": { + "description": "Cppcheck is a static code analysis tool for the C and C++ programming languages.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Cppcheck | Cppcheck is a static code analysis tool for the C and C++ programming languages. | v2.21.0", + "type": "boolean" + } + } + }, + "opengrep": { + "description": "OpenGrep is a high-performance static code analysis engine, compatible with Semgrep configurations.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable OpenGrep | OpenGrep is a high-performance static code analysis engine for finding security vulnerabilities and bugs across 17+ languages. | v1.26.0", + "type": "boolean" + } + } + }, + "semgrep": { + "description": "Semgrep is a static analysis tool designed to scan code for security vulnerabilities and code quality issues.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Semgrep | Semgrep is a static analysis tool designed to scan code for security vulnerabilities and code quality issues. | Enable Semgrep integration. | v1.170.0", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the Semgrep configuration file relative to the repository.", + "type": "string" + } + } + }, + "circleci": { + "description": "CircleCI tool is a static checker for CircleCI config files.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable CircleCI | CircleCI tool is a static checker for CircleCI config files. | v0.1.38646", + "type": "boolean" + } + } + }, + "clippy": { + "description": "Clippy is a collection of lints to catch common mistakes and improve your Rust code.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Clippy | Clippy is a collection of lints to catch common mistakes and improve your Rust code. | Enable Clippy integration.", + "type": "boolean" + } + } + }, + "sqlfluff": { + "description": "SQLFluff is an open source, dialect-flexible and configurable SQL linter.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable SQLFluff | SQLFluff is an open source, dialect-flexible and configurable SQL linter. | v4.2.2", + "type": "boolean" + }, + "config_file": { + "description": "Optional path to the SQLFluff configuration file relative to the repository. Use this when the config file is not named one of SQLFluff's default filenames.", + "type": "string" + } + } + }, + "squawk": { + "description": "Configuration for Squawk to lint Postgres migrations and SQL for safe schema changes", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Squawk for Postgres migration linting | Detects unsafe schema changes that can cause downtime or blocking locks | v2.61.0", + "type": "boolean" + } + } + }, + "trivy": { + "description": "Trivy is a comprehensive security scanner that detects misconfigurations and secrets in Infrastructure as Code files", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Trivy for security scanning of IaC files (Terraform, Kubernetes, Docker, etc.) | v0.72.0", + "type": "boolean" + } + } + }, + "prismaLint": { + "description": "Configuration for Prisma Schema linting to ensure schema file quality", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Prisma Schema linting | Prisma Schema linting helps maintain consistent and error-free schema files | v0.13.1", + "type": "boolean" + } + } + }, + "pylint": { + "description": "Pylint is a Python static code analysis tool.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Pylint | Pylint is a Python static code analysis tool. | v4.0.6", + "type": "boolean" + } + } + }, + "oxc": { + "description": "Oxlint is a JavaScript/TypeScript linter for OXC written in Rust.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Oxlint | Oxlint is a JavaScript/TypeScript linter for OXC written in Rust. | v1.76.0", + "type": "boolean" + } + } + }, + "shopifyThemeCheck": { + "description": "Configuration for Shopify Theme Check to ensure theme quality and best practices", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Shopify Theme Check | A linter for Shopify themes that helps you follow Shopify theme & Liquid best practices | cli 4.1.0 | theme 3.58.2", + "type": "boolean" + } + } + }, + "luacheck": { + "description": "Configuration for Lua code linting to ensure code quality", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Lua code linting | Luacheck helps maintain consistent and error-free Lua code | v1.2.0", + "type": "boolean" + } + } + }, + "brakeman": { + "description": "Brakeman is a static analysis security vulnerability scanner for Ruby on Rails applications. | v8.0.5", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Brakeman | Brakeman is a static analysis security vulnerability scanner for Ruby on Rails applications. | v8.0.5", + "type": "boolean" + } + } + }, + "dotenvLint": { + "description": "dotenv-linter is a tool for checking and fixing .env files for problems and best practices", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable dotenv-linter | dotenv-linter is a tool for checking and fixing .env files for problems and best practices | v4.0.0", + "type": "boolean" + } + } + }, + "htmlhint": { + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable HTMLHint | HTMLHint is a static code analysis tool for HTML files. | Enable HTMLHint integration. | v1.9.2", + "type": "boolean" + } + }, + "additionalProperties": false, + "description": "HTMLHint is a static code analysis tool for HTML files." + }, + "stylelint": { + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Stylelint | Stylelint is a linter for stylesheets (CSS, SCSS, Sass, Less, SugarSS, Stylus) that helps avoid errors and enforce conventions. | Enable Stylelint integration. | v17.14.0", + "type": "boolean" + } + }, + "additionalProperties": false, + "description": "Stylelint is a linter for stylesheets (CSS, SCSS, Sass, Less, SugarSS, Stylus) that helps avoid errors and enforce conventions." + }, + "checkmake": { + "description": "checkmake is a linter for Makefiles.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable checkmake | checkmake is a linter for Makefiles. | v0.3.2", + "type": "boolean" + } + } + }, + "osvScanner": { + "description": "OSV Scanner is a tool for vulnerability package scanning.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable OSV Scanner | OSV Scanner is a tool for vulnerability package scanning | v2.4.0", + "type": "boolean" + } + } + }, + "oasdiff": { + "description": "oasdiff detects breaking changes between OpenAPI specifications.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable oasdiff | oasdiff detects breaking changes between OpenAPI specifications. | v1.27.0", + "type": "boolean" + } + } + }, + "reactDoctor": { + "description": "React Doctor scans React codebases for security, performance, correctness, and accessibility issues.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable React Doctor | React Doctor scans React codebases for security, performance, correctness, and accessibility issues. | v0.9.3", + "type": "boolean" + } + } + }, + "presidio": { + "description": "Microsoft Presidio Analyzer 2.2.364 detects sensitive identifiers (including payment cards, US SSN, cryptocurrency wallets, and phone numbers) in changed files. Tune entities, thresholds, and languages in repository Presidio configuration (for example .presidiocli or AnalyzerEngineProvider YAML); the built-in scan uses fixed defaults and is skipped when that configuration is present.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Microsoft Presidio Analyzer for high-signal PII in changed files | v2.2.364", + "type": "boolean" + } + } + }, + "blinter": { + "description": "Blinter is a linter for Windows batch files that provides comprehensive static analysis to identify syntax errors, security vulnerabilities, performance issues, and style problems.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable Blinter | Blinter is a linter for Windows batch files that provides comprehensive static analysis to identify syntax errors, security vulnerabilities, performance issues, and style problems. | v1.1.7", + "type": "boolean" + } + } + }, + "smartyLint": { + "description": "smarty-lint is a linter for Smarty 3 template files that checks for common issues such as incorrect operator usage, naming conventions, empty blocks, and unquoted strings.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable smarty-lint | smarty-lint is a linter for Smarty 3 template files that checks for common issues such as incorrect operator usage, naming conventions, empty blocks, and unquoted strings. | v0.3.3", + "type": "boolean" + } + } + }, + "emberTemplateLint": { + "description": "ember-template-lint is a linter for Handlebars template files that checks for common issues such as accessibility violations, deprecated patterns, and template anti-patterns.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable ember-template-lint | ember-template-lint is a linter for Handlebars template files that checks for common issues such as accessibility violations, deprecated patterns, and template anti-patterns. | v7.9.3", + "type": "boolean" + } + } + }, + "skillspector": { + "description": "SkillSpector is a security scanner for AI agent skills that detects vulnerabilities, malicious patterns, and security risks", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable SkillSpector | SkillSpector is a security scanner for AI agent skills. It detects vulnerabilities, malicious patterns, and security risks in SKILL.md manifests and MCP configurations. | v2.5.1", + "type": "boolean" + } + } + }, + "psscriptanalyzer": { + "description": "PSScriptAnalyzer is a static code checker for PowerShell scripts and modules.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enable PSScriptAnalyzer | PSScriptAnalyzer is a static code checker for PowerShell scripts and modules. | v1.25.0", + "type": "boolean" + } + } + } + } + } + } + }, + "chat": { + "default": {}, + "type": "object", + "properties": { + "art": { + "default": true, + "description": "Generate art in chat responses (ASCII or emoji).", + "type": "boolean" + }, + "allow_non_org_members": { + "default": true, + "description": "Allow non-organization members to interact with CodeRabbit in comment chat. Set to false to restrict issue/review comment interactions to organization members on GitHub organization repositories. This does not affect automatic PR review eligibility.", + "type": "boolean" + }, + "auto_reply": { + "default": true, + "description": "Let CodeRabbit reply automatically without requiring a mention/tag.", + "type": "boolean" + }, + "integrations": { + "default": {}, + "type": "object", + "properties": { + "jira": { + "default": {}, + "type": "object", + "properties": { + "usage": { + "default": "auto", + "description": "Jira | Allow creating Jira issues from chat. 'auto' disables the integration for public repositories.", + "type": "string", + "enum": ["auto", "enabled", "disabled"] + } + } + }, + "linear": { + "default": {}, + "type": "object", + "properties": { + "usage": { + "default": "auto", + "description": "Linear | Allow creating Linear issues from chat. 'auto' disables the integration for public repositories.", + "type": "string", + "enum": ["auto", "enabled", "disabled"] + } + } + } + } + } + } + }, + "knowledge_base": { + "default": {}, + "type": "object", + "properties": { + "opt_out": { + "default": false, + "description": "Opt Out | Disable knowledge base features that require data retention. Opting out removes any existing stored knowledge base data.", + "type": "boolean" + }, + "web_search": { + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Web Search | Use web search to gather additional context.", + "type": "boolean" + } + } + }, + "code_guidelines": { + "description": "Use your coding guideline documents (see File Patterns) as review criteria.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Enabled | Apply your organization's coding standards during reviews.", + "type": "boolean" + }, + "filePatterns": { + "default": [], + "description": "File Patterns | Patterns for your coding guideline documents. CodeRabbit scans these files to learn your standards and apply them during reviews. Multiple files supported; file names are case-sensitive. Defaults include: (**/.cursorrules, .github/copilot-instructions.md, **/CLAUDE.md, **/GEMINI.md, **/.cursor/rules/*, **/.windsurfrules, **/.clinerules/*, **/.rules/*, **/AGENT.md, **/AGENTS.md, **/REVIEW.md).", + "type": "array", + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "object", + "properties": { + "files": { + "type": "string", + "description": "Files | Comma-separated glob patterns for guideline files (e.g., `**/AGENTS.md`). Multiple patterns supported. File names are case-sensitive." + }, + "applyTo": { + "type": "string", + "description": "Apply To | Comma-separated glob patterns for files these guidelines applies to (e.g., `**/*.ts`). Multiple patterns supported. File names are case-sensitive." + } + }, + "required": ["files", "applyTo"] + } + ] + } + } + } + }, + "learnings": { + "default": {}, + "type": "object", + "properties": { + "scope": { + "default": "auto", + "description": "Learnings | Choose scope: 'local' (repo), 'global' (org), or 'auto' (local for public repos, global for private repos).", + "type": "string", + "enum": ["local", "global", "auto"] + }, + "approval_delay": { + "default": 0, + "description": "Days admins have to approve or reject a learning before it is automatically applied. Must be an integer between 0 and 30. Set to 0 to apply learnings immediately without approval.", + "type": "integer", + "minimum": 0, + "maximum": 30 + } + } + }, + "issues": { + "default": {}, + "type": "object", + "properties": { + "scope": { + "default": "auto", + "description": "Issues | Choose scope for GitHub/GitLab issues: 'local' (repo), 'global' (org), or 'auto' (local for public repos, global for private repos).", + "type": "string", + "enum": ["local", "global", "auto"] + } + } + }, + "jira": { + "default": {}, + "type": "object", + "properties": { + "usage": { + "default": "auto", + "description": "Jira | Use Jira as a knowledge source. 'auto' disables the integration for public repositories.", + "type": "string", + "enum": ["auto", "enabled", "disabled"] + }, + "project_keys": { + "default": [], + "description": "Jira Project Keys | Restrict Jira context to these projects.", + "type": "array", + "items": { + "type": "string" + } + }, + "excluded_project_keys": { + "default": [], + "description": "Jira Excluded Project Keys | Never use these Jira projects as CodeRabbit context, regardless of repository allowlists. Managed at the workspace level as a security policy; exclusions always take precedence over any allowlist.", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "linear": { + "default": {}, + "type": "object", + "properties": { + "usage": { + "default": "auto", + "description": "Linear | Use Linear as a knowledge source. 'auto' disables the integration for public repositories.", + "type": "string", + "enum": ["auto", "enabled", "disabled"] + }, + "team_keys": { + "default": [], + "description": "Linear Team Keys | Restrict Linear context to these teams (e.g. 'ENG').", + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "pull_requests": { + "default": {}, + "type": "object", + "properties": { + "scope": { + "default": "auto", + "description": "PRs | Choose scope: 'local' (repo), 'global' (org), or 'auto' (local for public repos, global for private repos).", + "type": "string", + "enum": ["local", "global", "auto"] + } + } + }, + "mcp": { + "default": {}, + "type": "object", + "properties": { + "usage": { + "default": "auto", + "description": "MCP | Use MCP servers as a knowledge source. 'auto' disables the integration for public repositories.", + "type": "string", + "enum": ["auto", "enabled", "disabled"] + }, + "disabled_servers": { + "description": "Disabled MCP Servers | Specify MCP server labels to disable (case-insensitive). These servers will be excluded from reviews and knowledge base queries.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "automatic_repository_linking": { + "default": false, + "description": "Automatic Repository Linking | When enabled, CodeRabbit automatically detects and links related repositories in your organization to identify breaking changes and downstream impact during PR reviews.", + "type": "boolean" + }, + "linked_repositories": { + "default": [], + "description": "Linked Repositories | Repositories that CodeRabbit should consider when reviewing PRs in this repo. Use this to surface cross-repo dependencies and catch breaking changes across related codebases.", + "maxItems": 20, + "type": "array", + "items": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "pattern": "^[a-zA-Z0-9](?:[\\w .-]*[\\w.-])?(?:\\/(?:[a-zA-Z0-9](?:[\\w .-]*[\\w.-])?|\\.[a-zA-Z0-9](?:[\\w .-]*[\\w.-])?))+$", + "description": "Repository name in owner/repo format (e.g., GitHub: myorg/backend-api, Azure DevOps: My Project/backend-api, GitLab: group/subgroup/repo, Bitbucket: workspace/repo)" + }, + "instructions": { + "default": "", + "description": "Optionally provide description and guidance on what this repository contains for CodeRabbit to consider during reviews. Example: 'Contains REST API endpoints and database models.'", + "type": "string", + "maxLength": 2000 + } + }, + "required": ["repository"], + "additionalProperties": false + } + } + } + }, + "code_generation": { + "default": {}, + "type": "object", + "properties": { + "docstrings": { + "default": { + "path_instructions": [] + }, + "description": "Docstring Generation | Settings for generating docstrings.", + "type": "object", + "properties": { + "language": { + "default": "en-US", + "description": "Language for generated docstrings (ISO language code).", + "type": "string", + "enum": [ + "de", + "de-DE", + "de-AT", + "de-CH", + "en", + "en-US", + "en-AU", + "en-GB", + "en-CA", + "en-NZ", + "en-ZA", + "es", + "es-AR", + "fr", + "fr-CA", + "fr-CH", + "fr-BE", + "nl", + "nl-BE", + "pt-AO", + "pt", + "pt-BR", + "pt-MZ", + "pt-PT", + "ar", + "ast-ES", + "ast", + "be-BY", + "be", + "br-FR", + "br", + "ca-ES", + "ca", + "ca-ES-valencia", + "ca-ES-balear", + "da-DK", + "da", + "de-DE-x-simple-language", + "el-GR", + "el", + "eo", + "fa", + "ga-IE", + "ga", + "gl-ES", + "gl", + "it", + "ja-JP", + "ja", + "km-KH", + "km", + "ko-KR", + "ko", + "pl-PL", + "pl", + "ro-RO", + "ro", + "ru-RU", + "ru", + "sk-SK", + "sk", + "sl-SI", + "sl", + "sv", + "ta-IN", + "ta", + "tl-PH", + "tl", + "tr", + "uk-UA", + "uk", + "zh-CN", + "zh", + "zh-TW", + "crh-UA", + "crh", + "cs-CZ", + "cs", + "nb", + "no", + "nl-NL", + "de-DE-x-simple-language-DE", + "es-ES", + "it-IT", + "fa-IR", + "sv-SE", + "de-LU", + "fr-FR", + "bg-BG", + "bg", + "he-IL", + "he", + "hi-IN", + "hi", + "vi-VN", + "vi", + "th-TH", + "th", + "bn-BD", + "bn" + ], + "enumNames": [ + "German", + "German (Germany)", + "German (Austria)", + "German (Swiss)", + "English", + "English (US)", + "English (Australian)", + "English (GB)", + "English (Canadian)", + "English (New Zealand)", + "English (South African)", + "Spanish", + "Spanish (voseo)", + "French", + "French (Canada)", + "French (Switzerland)", + "French (Belgium)", + "Dutch", + "Dutch (Belgium)", + "Portuguese (Angola preAO)", + "Portuguese", + "Portuguese (Brazil)", + "Portuguese (Moçambique preAO)", + "Portuguese (Portugal)", + "Arabic", + "Asturian", + "Asturian", + "Belarusian", + "Belarusian", + "Breton", + "Breton", + "Catalan", + "Catalan", + "Catalan (Valencian)", + "Catalan (Balearic)", + "Danish", + "Danish", + "Simple German", + "Greek", + "Greek", + "Esperanto", + "Persian", + "Irish", + "Irish", + "Galician", + "Galician", + "Italian", + "Japanese", + "Japanese", + "Khmer", + "Khmer", + "Korean", + "Korean", + "Polish", + "Polish", + "Romanian", + "Romanian", + "Russian", + "Russian", + "Slovak", + "Slovak", + "Slovenian", + "Slovenian", + "Swedish", + "Tamil", + "Tamil", + "Tagalog", + "Tagalog", + "Turkish", + "Ukrainian", + "Ukrainian", + "Simplified Chinese", + "Simplified Chinese", + "Traditional Chinese", + "Crimean Tatar", + "Crimean Tatar", + "Czech", + "Czech", + "Norwegian", + "Norwegian (Bokmål)", + "Dutch (Netherlands)", + "Simple German", + "Spanish", + "Italian", + "Persian", + "Swedish", + "German (Luxembourg)", + "French", + "Bulgarian", + "Bulgarian", + "Hebrew", + "Hebrew", + "Hindi", + "Hindi", + "Vietnamese", + "Vietnamese", + "Thai", + "Thai", + "Bengali", + "Bengali" + ] + }, + "path_instructions": { + "default": [], + "description": "Path Instructions | Add path-specific guidelines for docstring generation.", + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path glob pattern. Example: `**/*.js`." + }, + "instructions": { + "type": "string", + "maxLength": 20000, + "description": "Additional docstring-generation guidelines for matching paths." + } + }, + "required": ["path", "instructions"] + } + } + } + }, + "unit_tests": { + "default": { + "path_instructions": [] + }, + "description": "Unit Test Generation | Settings for generating unit tests.", + "type": "object", + "properties": { + "path_instructions": { + "default": [], + "description": "Path Instructions | Add path-specific guidelines for unit test generation.", + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "File path glob pattern. Example: `**/*.js`." + }, + "instructions": { + "type": "string", + "maxLength": 20000, + "description": "Additional unit-test-generation guidelines for matching paths." + } + }, + "required": ["path", "instructions"] + } + } + } + } + } + }, + "issue_enrichment": { + "default": {}, + "type": "object", + "properties": { + "auto_enrich": { + "description": "Settings for automatic issue enrichment.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": false, + "description": "Automatic Issue Enrichment | Analyze and enrich issues with additional context (related code, potential solutions, complexity assessment).", + "type": "boolean" + } + } + }, + "planning": { + "description": "Settings for issue planning.", + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Issue Planning | Generate an implementation plan for issues (early preview).", + "type": "boolean" + }, + "auto_planning": { + "default": {}, + "type": "object", + "properties": { + "enabled": { + "default": true, + "description": "Automatic Planning | Trigger issue planning based on labels.", + "type": "boolean" + }, + "labels": { + "default": [], + "description": "Labels that trigger automatic issue planning. Labels starting with '!' are negative matches. Examples: ['feature', 'enhancement'] plans issues with either label. ['!wip'] plans all issues except those labeled 'wip'. ['feature', '!wip'] plans issues labeled 'feature' but not 'wip'.", + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + }, + "labeling": { + "description": "Settings for issue labeling.", + "default": {}, + "type": "object", + "properties": { + "labeling_instructions": { + "default": [], + "description": "Labeling Instructions | Define issue labels to suggest and when to suggest them.", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "Label to suggest for the issue. Example: enhancement" + }, + "instructions": { + "type": "string", + "maxLength": 3000, + "description": "Instructions for the label. Example: New feature or request." + } + }, + "required": ["label", "instructions"] + } + }, + "auto_apply_labels": { + "default": false, + "description": "Automatically apply suggested labels to the issue. When enabled without labeling instructions, labels are auto-suggested based on similar issues.", + "type": "boolean" + } + } + } + } + } + }, + "additionalProperties": false +} diff --git a/.github/coderabbit-config/schema_drift.py b/.github/coderabbit-config/schema_drift.py new file mode 100644 index 00000000..6a86798e --- /dev/null +++ b/.github/coderabbit-config/schema_drift.py @@ -0,0 +1,274 @@ +#!/usr/bin/env python3 +"""Compare the vendored CodeRabbit schema against a freshly fetched one. + +`check_coderabbit_config.py` validates against a VENDORED schema on purpose: a +live fetch would make every consumer's CI depend on a third-party endpoint, and +an upstream tightening would turn CI red across the fleet with no change on our +side. The cost of vendoring is that the copy rots silently — so +`refresh-coderabbit-schema.yml` fetches upstream on a schedule and runs this to +decide whether the drift is worth a PR, and to write the summary that makes that +PR reviewable in thirty seconds instead of by reading a 75 KB JSON diff. + +Two deliberate behaviours: + + * The comparison is SEMANTIC (canonical JSON), not byte-for-byte. Upstream + re-serializing the same schema with different whitespace or key order is not + drift, and opening a PR for it trains everyone to ignore these PRs. + * A fetched file that is not a JSON Schema object is a hard ERROR, never + "no drift". The schema URL 301-redirects, and a `curl` without `-L` writes a + 167-byte HTML redirect stub; treating that as "nothing changed" would freeze + the vendored copy forever with a green run every week saying so. + +Run locally: + python3 .github/coderabbit-config/schema_drift.py \\ + --vendored .github/coderabbit-config/schema.v2.json --fetched /tmp/new.json + +Exit codes: 0 = no drift, 1 = drifted (summary on stdout), 2 = unusable input. +""" + +import argparse +import json +import sys + +# Cap the per-section lists so one sweeping upstream restructure cannot produce a +# PR body GitHub truncates. The counts are always reported in full — only the +# enumeration is capped, and the cap says so when it bites. +MAX_LISTED = 25 + + +class DriftInputError(Exception): + """A file that cannot serve as a schema — not a drift verdict.""" + + +def load(path, label): + try: + with open(path, "r", encoding="utf-8") as f: + raw = f.read() + except OSError as exc: + raise DriftInputError(f"cannot read the {label} schema at {path}: {exc}") + try: + data = json.loads(raw) + except json.JSONDecodeError as exc: + raise DriftInputError( + f"the {label} schema at {path} is not valid JSON: {exc}. If this is " + f"the fetched copy, the most likely cause is a redirect stub — the " + f"schema URL 301-redirects, so the fetch must use `curl -fsSL`." + ) + if not isinstance(data, dict) or not isinstance(data.get("properties"), dict): + raise DriftInputError( + f"the {label} schema at {path} is not a JSON Schema object with a " + f"`properties` map — refusing to treat it as a schema." + ) + return data + + +def canonical(schema): + return json.dumps(schema, sort_keys=True, separators=(",", ":")) + + +# Keywords whose value is a single subschema, and whose contents are therefore +# as capable of holding a cap or a property as `properties` itself. +_SUBSCHEMA_KEYWORDS = ( + "additionalProperties", + "unevaluatedProperties", + "propertyNames", + "contains", + "not", + "if", + "then", + "else", +) + +# Keywords whose value is a LIST of subschemas. +_BRANCH_KEYWORDS = ("anyOf", "oneOf", "allOf") + + +def _subschemas(schema): + """Yield `(dotted path, node, kind)` for every subschema in the document. + + `kind` is `"property"` when the node was reached as a named property (what + `property_paths` reports), and `""` otherwise. + + Descending only through `properties` and a dict-valued `items` — the obvious + walk — is not enough, and the vendored copy already proves it: it uses + `knowledge_base.code_guidelines.filePatterns.items.anyOf` and + `reviews.mutually_exclusive_groups.additionalProperties` today. A `maxLength` + tightened inside one of those invalidates a config exactly as hard as one on a + plain property, but the narrow walk could not see it — and because the + property path itself is unchanged, `added`/`removed` would be empty too, so + the summary would claim "the drift is elsewhere". + + Paths are stable and distinct across versions, which is the whole basis of + the diff: a combinator branch carries its index (`x`) so two + branches constraining the same location cannot collide into one entry. + """ + # Cycle backstop. `json.load` never shares objects, so nothing is skipped + # today; this only stops a self-referential schema from recursing forever. + seen = set() + + def walk(node, path, kind): + if not isinstance(node, dict) or id(node) in seen: + return + seen.add(id(node)) + yield path, node, kind + + for name, sub in (node.get("properties") or {}).items(): + yield from walk(sub, f"{path}.{name}" if path else name, "property") + for pattern, sub in (node.get("patternProperties") or {}).items(): + child = f"{{{pattern}}}" + yield from walk(sub, f"{path}.{child}" if path else child, "property") + for name, sub in (node.get("$defs") or node.get("definitions") or {}).items(): + yield from walk(sub, f"{path}<$defs.{name}>", "") + + items = node.get("items") + if isinstance(items, dict): + yield from walk(items, f"{path}[]", "") + elif isinstance(items, list): + # Tuple validation: each entry constrains one position. + for index, sub in enumerate(items): + yield from walk(sub, f"{path}[{index}]", "") + + for keyword in _SUBSCHEMA_KEYWORDS: + sub = node.get(keyword) + if isinstance(sub, dict): + yield from walk(sub, f"{path}<{keyword}>", "") + for keyword in _BRANCH_KEYWORDS: + branches = node.get(keyword) + if isinstance(branches, list): + for index, sub in enumerate(branches): + yield from walk(sub, f"{path}<{keyword}[{index}]>", "") + + yield from walk(schema, "", "") + + +def property_paths(schema): + """Every dotted property path in the schema, e.g. `reviews.tools.eslint.enabled`.""" + return {path for path, _node, kind in _subschemas(schema) if kind == "property"} + + +def length_caps(schema): + """`{dotted path: maxLength}` for every capped string in the schema. + + Called out separately from the raw property diff because a tightened cap is + the one drift class that can turn a config that has been valid for months + into one CodeRabbit rejects whole, with no change on the config's side. + """ + caps = {} + for path, node, _kind in _subschemas(schema): + cap = node.get("maxLength") + if isinstance(cap, int): + caps[path or "(document root)"] = cap + return caps + + +def _bullets(title, items): + if not items: + return [] + out = [f"**{title}** ({len(items)}):", ""] + for entry in sorted(items)[:MAX_LISTED]: + out.append(f"- `{entry}`") + if len(items) > MAX_LISTED: + out.append(f"- …and {len(items) - MAX_LISTED} more (see the diff).") + out.append("") + return out + + +def summarize(vendored, fetched): + """A Markdown summary of what changed, for the refresh PR body.""" + old_paths, new_paths = property_paths(vendored), property_paths(fetched) + old_caps, new_caps = length_caps(vendored), length_caps(fetched) + + added = new_paths - old_paths + removed = old_paths - new_paths + tightened = [] + loosened = [] + # The UNION of both sides, not just the fetched caps. Two drift classes hide + # in the difference, and the first is the one this whole section exists to + # lead with: + # * upstream ADDS a cap to a property that was uncapped + # (`reviews.high_level_summary_instructions`, `reviews.auto_title_instructions` + # and `pre_merge_checks.title.requirements` are all uncapped today) — the + # single most config-invalidating change upstream can make; + # * upstream REMOVES a cap, which never appears in `new_caps` at all. + # In both cases the property path is unchanged, so `added`/`removed` are + # empty too — skipping them would print "No property or `maxLength` changes" + # over exactly the drift a reviewer must not miss. + for path in sorted(set(old_caps) | set(new_caps)): + was, now = old_caps.get(path), new_caps.get(path) + if was == now: + continue + if was is None: + tightened.append(f"{path}: uncapped → {now}") + elif now is None: + loosened.append(f"{path}: {was} → uncapped") + else: + (tightened if now < was else loosened).append(f"{path}: {was} → {now}") + + lines = [] + # Tightened caps first: this is the only class that can retroactively + # invalidate a config nobody touched, so it must not sit below a hundred + # cosmetic additions. + if tightened: + lines += _bullets("⚠️ Tightened `maxLength` caps — may invalidate existing configs", tightened) + lines += _bullets("Loosened `maxLength` caps", loosened) + lines += _bullets("Removed properties", removed) + lines += _bullets("Added properties", added) + + if not lines: + lines = [ + "No property or `maxLength` changes — the drift is elsewhere in the " + "schema (a description, default, enum or type). Read the diff.", + "", + ] + return "\n".join(lines).rstrip() + "\n" + + +def main(argv=None): + parser = argparse.ArgumentParser(description="Detect CodeRabbit schema drift.") + parser.add_argument("--vendored", required=True, help="Path to the committed schema.") + parser.add_argument("--fetched", required=True, help="Path to the freshly fetched schema.") + parser.add_argument( + "--summary-out", + help="Write the Markdown drift summary here as well as to stdout.", + ) + args = parser.parse_args(argv) + + try: + vendored = load(args.vendored, "vendored") + fetched = load(args.fetched, "fetched") + + if canonical(vendored) == canonical(fetched): + print("No drift: the vendored schema matches upstream.") + return 0 + + summary = summarize(vendored, fetched) + # Written BEFORE exit 1 is returned, and inside this guard: exit 1 tells + # the caller "drifted", and the caller acts on it by vendoring the fetch + # and force-resetting a shared branch. Reporting drift while the summary + # that explains it does not exist strands that branch behind a PR step + # that then fails trying to read it. + if args.summary_out: + with open(args.summary_out, "w", encoding="utf-8") as f: + f.write(summary) + except DriftInputError as exc: + print(f"::error::coderabbit-schema-refresh: {exc}") + return 2 + except Exception as exc: # noqa: BLE001 — deliberate, see below + # Anything unexpected — a non-UTF-8 fetch decoded here, a RecursionError + # on a degenerate schema, an unwritable --summary-out — must NOT reach the + # caller as Python's default exit 1, because 1 is the drift verdict and + # the caller force-resets a branch on it. A failure to compare is not a + # comparison: it comes back as 2, like every other unusable input. + print( + f"::error::coderabbit-schema-refresh: unexpected failure comparing the " + f"schemas ({type(exc).__name__}: {exc}) — treating this as " + f"'could not compare', not as drift." + ) + return 2 + + print(summary) + return 1 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.github/coderabbit-config/tests/test_check_coderabbit_config.py b/.github/coderabbit-config/tests/test_check_coderabbit_config.py new file mode 100644 index 00000000..35e191a5 --- /dev/null +++ b/.github/coderabbit-config/tests/test_check_coderabbit_config.py @@ -0,0 +1,398 @@ +"""Unit tests for the .coderabbit.yaml validator. + +The fixtures below are deliberately built from the failure classes that actually +happened, not from invented ones: + + * an over-long `tone_instructions` — the 446-char field that had the whole + config rejected on one repo, fixed twice in six days by two independent + tickets because nothing detected it; + * a top-level `tools:` block that belongs under `reviews:` — three org repos + carried this at the time of writing, and on one of them it silently inverted + a `golangci-lint: enabled: false` into the schema default of `true`. + +Every test validates against the REAL vendored schema rather than a toy one, so +a schema refresh that would change a verdict fails here first. +""" + +import io +import json +import os +import sys +import unittest +from contextlib import redirect_stdout + +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +import check_coderabbit_config as checker # noqa: E402 + +SCHEMA_PATH = os.path.join( + os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "schema.v2.json" +) + +with open(SCHEMA_PATH, "r", encoding="utf-8") as _f: + SCHEMA = json.load(_f) + +VALID = """\ +language: en-US +tone_instructions: Be concise. +reviews: + profile: chill + request_changes_workflow: false + tools: + golangci-lint: + enabled: false + path_instructions: + - path: "**/*.go" + instructions: Prefer table-driven tests. +""" + +# The real shape: the block is written at the document root instead of under +# `reviews:`, so CodeRabbit strips it and the disable never applies. +MISPLACED_TOOLS = """\ +reviews: + profile: chill +tools: + # Project uses go vet + staticcheck, not golangci-lint + golangci-lint: + enabled: false +""" + +OVERLONG_TONE = "tone_instructions: " + ("x" * 300) + "\n" + +MALFORMED = """\ +reviews: + profile: chill + path_filters: + - "!**/*.lock" +""" + + +def severities(findings): + return [f[0] for f in findings] + + +def messages(findings): + return [f[3] for f in findings] + + +class ValidateTest(unittest.TestCase): + def test_valid_config_produces_nothing(self): + findings, notes = checker.validate(VALID, SCHEMA) + self.assertEqual(findings, [], msg=f"unexpected findings: {messages(findings)}") + self.assertEqual(notes, []) + + def test_overlong_tone_instructions_fails_with_actual_and_permitted(self): + findings, _ = checker.validate(OVERLONG_TONE, SCHEMA) + self.assertEqual(severities(findings), ["error"]) + message = messages(findings)[0] + self.assertIn("tone_instructions", message) + self.assertIn("300 characters", message) + self.assertIn("250", message) + + def test_overlong_tone_instructions_still_fails_without_strict(self): + # The severity split must not be read as "strict mode is what makes this + # check bite" — a maxLength violation is file-rejecting either way. + findings, _ = checker.validate(OVERLONG_TONE, SCHEMA, strict_unknown_keys=False) + self.assertEqual(severities(findings), ["error"]) + + def test_misplaced_tools_warns_by_default_and_names_the_root_key(self): + findings, _ = checker.validate(MISPLACED_TOOLS, SCHEMA) + self.assertEqual(severities(findings), ["warning"]) + _severity, path, line, message = findings[0] + self.assertEqual(path, "tools") + self.assertIn("unknown key `tools`", message) + self.assertIn("document root", message) + # The whole point of the hint: name where it belongs. + self.assertIn("reviews.tools", message) + # And point at the key itself, not at the file. + self.assertEqual(line, 3) + + def test_misplaced_tools_fails_under_strict_unknown_keys(self): + findings, _ = checker.validate(MISPLACED_TOOLS, SCHEMA, strict_unknown_keys=True) + self.assertEqual(severities(findings), ["error"]) + self.assertIn("unknown key `tools`", messages(findings)[0]) + + def test_malformed_yaml_fails_with_a_line(self): + findings, _ = checker.validate(MALFORMED, SCHEMA) + self.assertEqual(severities(findings), ["error"]) + _severity, _path, line, message = findings[0] + self.assertIn("not valid YAML", message) + self.assertIsNotNone(line) + + def test_malformed_yaml_fails_even_with_unknown_keys_relaxed(self): + findings, _ = checker.validate(MALFORMED, SCHEMA, strict_unknown_keys=False) + self.assertEqual(severities(findings), ["error"]) + + def test_type_error_fails(self): + # A wrong-typed enum field trips both `type` and `enum`; both are + # file-rejecting, so assert the severity of every finding rather than + # their count. + findings, _ = checker.validate("reviews:\n profile: 7\n", SCHEMA) + self.assertTrue(findings) + self.assertEqual(set(severities(findings)), {"error"}) + self.assertTrue(all("reviews.profile" in m for m in messages(findings))) + + def test_enum_error_fails(self): + findings, _ = checker.validate("reviews:\n profile: spicy\n", SCHEMA) + self.assertEqual(severities(findings), ["error"]) + self.assertIn("permitted values", messages(findings)[0]) + + def test_nested_maxlength_reports_the_full_path_and_a_line(self): + body = "x" * 21000 + text = ( + "reviews:\n" + " path_instructions:\n" + ' - path: "**/*.go"\n' + f" instructions: {body}\n" + ) + findings, _ = checker.validate(text, SCHEMA) + self.assertEqual(severities(findings), ["error"]) + _severity, path, line, message = findings[0] + self.assertEqual(path, "reviews.path_instructions[0].instructions") + self.assertEqual(line, 4) + self.assertIn("20000", message) + + def test_empty_document_is_a_note_not_a_finding(self): + findings, notes = checker.validate("# only a comment\n", SCHEMA) + self.assertEqual(findings, []) + self.assertEqual(len(notes), 1) + self.assertIn("empty document", notes[0]) + + def test_multiple_unknown_keys_are_reported_individually(self): + findings, _ = checker.validate("tools: {}\nnope: 1\n", SCHEMA) + self.assertEqual(sorted(f[1] for f in findings), ["nope", "tools"]) + + def test_non_mapping_document_fails(self): + findings, _ = checker.validate("- a\n- b\n", SCHEMA) + self.assertEqual(severities(findings), ["error"]) + + def test_workflow_command_injection_is_escaped(self): + # A key carrying a newline would otherwise close the annotation line and + # emit a second, author-chosen workflow command into a public log. + evil = '"bad\n::stop-commands::tok": 1\n' + findings, _ = checker.validate(evil, SCHEMA) + self.assertTrue(findings) + buf = io.StringIO() + with redirect_stdout(buf): + checker._emit(findings, [], ".coderabbit.yaml") + out = buf.getvalue() + self.assertNotIn("\n::stop-commands::tok", out) + self.assertIn("%0A", out) + + +class SchemaTest(unittest.TestCase): + """Assertions about the VENDORED schema itself. + + These are the facts the checker's value rests on. If a schema refresh changes + one, the refresh PR should say so out loud rather than quietly redefining + what the check means. + """ + + def test_root_is_closed(self): + # Everything about the unknown-key severity depends on this. + self.assertIs(SCHEMA.get("additionalProperties"), False) + + def test_tone_instructions_is_capped_at_250(self): + self.assertEqual(SCHEMA["properties"]["tone_instructions"]["maxLength"], 250) + + def test_tools_lives_under_reviews(self): + self.assertIn("tools", SCHEMA["properties"]["reviews"]["properties"]) + self.assertNotIn("tools", SCHEMA["properties"]) + + def test_golangci_lint_defaults_to_enabled(self): + # The reason a stripped root `tools:` block is a behaviour change and not + # a cosmetic one. + tools = SCHEMA["properties"]["reviews"]["properties"]["tools"]["properties"] + self.assertIs(tools["golangci-lint"]["properties"]["enabled"]["default"], True) + + +class LoadSchemaTest(unittest.TestCase): + def test_rejects_a_redirect_stub(self): + import tempfile + + with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as f: + f.write('"Moved"') + path = f.name + with self.assertRaises(checker.ConfigError): + checker.load_schema(path) + os.unlink(path) + + def test_reports_a_digest(self): + _schema, digest = checker.load_schema(SCHEMA_PATH) + self.assertEqual(len(digest), 64) + + +class MainTest(unittest.TestCase): + def _run(self, tmp, argv): + buf = io.StringIO() + with redirect_stdout(buf): + code = checker.main(argv) + return code, buf.getvalue() + + def test_absent_file_passes_and_says_so(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 0) + self.assertIn("nothing to validate", out) + self.assertIn("absent", out) + + def test_valid_file_exits_zero(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, ".coderabbit.yaml"), "w", encoding="utf-8") as f: + f.write(VALID) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 0, msg=out) + + def test_misplaced_tools_exits_zero_by_default_and_one_under_strict(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, ".coderabbit.yaml"), "w", encoding="utf-8") as f: + f.write(MISPLACED_TOOLS) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 0, msg=out) + self.assertIn("::warning ", out) + code, out = self._run( + tmp, ["--root", tmp, "--schema", SCHEMA_PATH, "--strict-unknown-keys"] + ) + self.assertEqual(code, 1) + self.assertIn("::error ", out) + + def test_overlong_tone_exits_one(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, ".coderabbit.yaml"), "w", encoding="utf-8") as f: + f.write(OVERLONG_TONE) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 1) + self.assertIn("::error ", out) + + def test_custom_config_path_is_honored(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, "configs.yaml"), "w", encoding="utf-8") as f: + f.write(OVERLONG_TONE) + # Default name is absent (and has no sibling spelling) -> pass; + # pointing at the real file -> fail. + code, _ = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 0) + code, _ = self._run( + tmp, ["--root", tmp, "--schema", SCHEMA_PATH, "--config", "configs.yaml"] + ) + self.assertEqual(code, 1) + + def test_the_other_spelling_is_validated_not_reported_absent(self): + # The quietest failure this checker can have: a repo on the `.coderabbit.yml` + # spelling leaves `config_file` at its default, and every PR forever gets a + # green check over a config nobody looked at. CodeRabbit honours both + # spellings, so the present one is the config in effect. + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, ".coderabbit.yml"), "w", encoding="utf-8") as f: + f.write(OVERLONG_TONE) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 1, msg=out) + self.assertIn("::warning::", out) + self.assertIn(".coderabbit.yml", out) + self.assertNotIn("absent — pass", out) + + def test_a_symlink_out_of_the_tree_is_refused_not_followed(self): + # abspath normalizes `..` but does not resolve symlinks, while isfile() + # and open() both follow them — so a config committed as a symlink would + # otherwise clear the containment guard and have the TARGET's content + # quoted into a public run log by a YAML error message. + import tempfile + + with tempfile.TemporaryDirectory() as outside: + secret = os.path.join(outside, "secret.yaml") + with open(secret, "w", encoding="utf-8") as f: + f.write("this: [is not: valid yaml\n") + with tempfile.TemporaryDirectory() as tmp: + os.symlink(secret, os.path.join(tmp, ".coderabbit.yaml")) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 2, msg=out) + self.assertIn("outside the checked-out repo root", out) + self.assertNotIn("is not valid yaml", out) + + def test_a_symlink_inside_the_tree_is_still_validated(self): + # The guard is containment, not "no symlinks": a repo that keeps its + # config behind an in-tree symlink is doing nothing wrong. + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + real = os.path.join(tmp, "real.yaml") + with open(real, "w", encoding="utf-8") as f: + f.write(OVERLONG_TONE) + os.symlink(real, os.path.join(tmp, ".coderabbit.yaml")) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 1, msg=out) + + def test_a_path_that_is_not_a_regular_file_exits_two(self): + # A directory or a dangling symlink is "I could not check", never a pass. + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + os.mkdir(os.path.join(tmp, ".coderabbit.yaml")) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 2, msg=out) + self.assertIn("not a regular file", out) + + with tempfile.TemporaryDirectory() as tmp: + os.symlink(os.path.join(tmp, "gone.yaml"), os.path.join(tmp, ".coderabbit.yaml")) + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 2, msg=out) + + def test_an_absurdly_large_config_is_refused_before_parsing(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(os.path.join(tmp, ".coderabbit.yaml"), "w", encoding="utf-8") as f: + f.write("# " + ("x" * (checker.MAX_CONFIG_BYTES + 10)) + "\n") + code, out = self._run(tmp, ["--root", tmp, "--schema", SCHEMA_PATH]) + self.assertEqual(code, 2, msg=out) + self.assertIn("refusing to read it", out) + + def test_the_config_path_is_escaped_in_the_banner(self): + # `config_file` is a workflow_call input a PR to the caller repo can edit; + # a newline in it would emit a second, attacker-chosen workflow command + # (`::stop-commands::` suppresses every annotation printed after it). + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + code, out = self._run( + tmp, + [ + "--root", + tmp, + "--schema", + SCHEMA_PATH, + "--config", + "a.yaml\n::stop-commands::x", + ], + ) + self.assertNotIn("\n::stop-commands::", out) + self.assertIn("%0A", out) + self.assertEqual(code, 0, msg=out) + + def test_unreadable_schema_exits_two(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + code, out = self._run( + tmp, ["--root", tmp, "--schema", os.path.join(tmp, "nope.json")] + ) + # 2, not 1: "I could not run the check" must never look like "the config + # is fine" OR like "the config is broken". + self.assertEqual(code, 2) + self.assertIn("::error::", out) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/coderabbit-config/tests/test_schema_drift.py b/.github/coderabbit-config/tests/test_schema_drift.py new file mode 100644 index 00000000..cfa187aa --- /dev/null +++ b/.github/coderabbit-config/tests/test_schema_drift.py @@ -0,0 +1,217 @@ +"""Unit tests for the vendored-schema drift detector.""" + +import io +import json +import os +import sys +import tempfile +import unittest +from contextlib import redirect_stdout + +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +import schema_drift # noqa: E402 + +VENDORED = os.path.join( + os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "schema.v2.json" +) + +BASE = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "additionalProperties": False, + "properties": { + "tone_instructions": {"type": "string", "maxLength": 250}, + "reviews": { + "type": "object", + "properties": {"profile": {"type": "string"}}, + }, + }, +} + + +def write(tmp, name, data, raw=None): + path = os.path.join(tmp, name) + with open(path, "w", encoding="utf-8") as f: + f.write(raw if raw is not None else json.dumps(data)) + return path + + +class LoadTest(unittest.TestCase): + def test_redirect_stub_is_an_error_not_no_drift(self): + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", None, raw='Moved') + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + self.assertEqual(code, 2) + self.assertIn("::error::", buf.getvalue()) + self.assertIn("curl -fsSL", buf.getvalue()) + + def test_json_that_is_not_a_schema_is_an_error(self): + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", {"hello": "world"}) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + self.assertEqual(code, 2) + + +class DriftTest(unittest.TestCase): + def test_identical_schemas_report_no_drift(self): + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", BASE) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + self.assertEqual(code, 0) + self.assertIn("No drift", buf.getvalue()) + + def test_reformatting_alone_is_not_drift(self): + # Byte-comparing would open a churn PR here; semantic comparison must not. + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", None, raw=json.dumps(BASE, indent=4, sort_keys=True)) + b = write(tmp, "b.json", None, raw=json.dumps(BASE, separators=(",", ":"))) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + self.assertEqual(code, 0) + + def test_tightened_cap_is_flagged_first_and_loudly(self): + tightened = json.loads(json.dumps(BASE)) + tightened["properties"]["tone_instructions"]["maxLength"] = 120 + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", tightened) + out = os.path.join(tmp, "summary.md") + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main( + ["--vendored", a, "--fetched", b, "--summary-out", out] + ) + self.assertEqual(code, 1) + with open(out, encoding="utf-8") as f: + summary = f.read() + self.assertIn("Tightened", summary.splitlines()[0]) + self.assertIn("tone_instructions: 250 → 120", summary) + + def test_added_and_removed_properties_are_listed_with_full_paths(self): + changed = json.loads(json.dumps(BASE)) + changed["properties"]["reviews"]["properties"]["tools"] = {"type": "object"} + del changed["properties"]["reviews"]["properties"]["profile"] + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", changed) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + summary = buf.getvalue() + self.assertEqual(code, 1) + self.assertIn("`reviews.tools`", summary) + self.assertIn("`reviews.profile`", summary) + + def test_description_only_drift_still_opens_a_pr_with_an_honest_summary(self): + changed = json.loads(json.dumps(BASE)) + changed["properties"]["reviews"]["description"] = "new prose" + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", changed) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + self.assertEqual(code, 1) + self.assertIn("Read the diff", buf.getvalue()) + + + def test_a_newly_capped_property_is_reported_as_tightened(self): + # The most config-invalidating change upstream can make: a field that was + # unbounded acquires a cap, so a config nobody touched is now rejected + # WHOLE. The path is unchanged, so added/removed are empty — before the + # union fix this printed "No property or maxLength changes". + capped = json.loads(json.dumps(BASE)) + capped["properties"]["reviews"]["properties"]["profile"]["maxLength"] = 40 + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", capped) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + summary = buf.getvalue() + self.assertEqual(code, 1) + self.assertIn("Tightened", summary.splitlines()[0]) + self.assertIn("reviews.profile: uncapped → 40", summary) + self.assertNotIn("the drift is elsewhere", summary) + + def test_a_removed_cap_is_reported_as_loosened(self): + loosened = json.loads(json.dumps(BASE)) + del loosened["properties"]["tone_instructions"]["maxLength"] + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + b = write(tmp, "b.json", loosened) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main(["--vendored", a, "--fetched", b]) + summary = buf.getvalue() + self.assertEqual(code, 1) + self.assertIn("Loosened", summary) + self.assertIn("tone_instructions: 250 → uncapped", summary) + self.assertNotIn("the drift is elsewhere", summary) + + def test_caps_and_properties_inside_combinators_are_visible(self): + # The vendored schema already uses both shapes (`filePatterns.items.anyOf`, + # `mutually_exclusive_groups.additionalProperties`), so a walk that stops + # at `properties`/dict-`items` is blind to drift the fleet would feel. + nested = json.loads(json.dumps(BASE)) + nested["properties"]["reviews"]["properties"]["groups"] = { + "type": "object", + "additionalProperties": { + "type": "array", + "items": {"anyOf": [{"type": "string", "maxLength": 60}]}, + }, + } + caps = schema_drift.length_caps(nested) + paths = schema_drift.property_paths(nested) + self.assertIn("reviews.groups", paths) + self.assertEqual( + caps["reviews.groups[]"], 60 + ) + + def test_an_unexpected_failure_exits_two_not_one(self): + # Exit 1 means DRIFTED, and the caller force-resets a shared branch on it. + # An unwritable --summary-out is not a verdict. + with tempfile.TemporaryDirectory() as tmp: + a = write(tmp, "a.json", BASE) + changed = json.loads(json.dumps(BASE)) + changed["properties"]["reviews"]["description"] = "new prose" + b = write(tmp, "b.json", changed) + out_dir = os.path.join(tmp, "summary-is-a-dir") + os.mkdir(out_dir) + buf = io.StringIO() + with redirect_stdout(buf): + code = schema_drift.main( + ["--vendored", a, "--fetched", b, "--summary-out", out_dir] + ) + self.assertEqual(code, 2) + self.assertIn("could not compare", buf.getvalue()) + + +class VendoredSchemaTest(unittest.TestCase): + def test_the_committed_schema_loads_as_a_schema(self): + # Guards the vendoring step itself: a truncated or stubbed commit of + # schema.v2.json would make every consumer's check pass vacuously. + schema = schema_drift.load(VENDORED, "vendored") + self.assertIn("reviews", schema["properties"]) + self.assertIs(schema.get("additionalProperties"), False) + + def test_the_committed_schema_has_the_documented_cap_set(self): + caps = schema_drift.length_caps(schema_drift.load(VENDORED, "vendored")) + self.assertEqual(caps["tone_instructions"], 250) + self.assertEqual(caps["reviews.path_instructions[].instructions"], 20000) + self.assertEqual(len(caps), 14) + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 44bc8009..fd41b80d 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -141,6 +141,32 @@ updates: default-days: 7 semver-major-days: 14 + # The PyYAML + jsonschema pins the .coderabbit.yaml validator installs + # (BE-7757). This is the repo's only Python dependency set, and it is + # hash-pinned with `--require-hashes` — which is exactly why it needs watching: + # a hash pin cannot float, so without Dependabot a security fix in either + # package never arrives and nothing fails to say so. Dependabot regenerates the + # hashes on a bump, so the file stays installable. + - package-ecosystem: "pip" + directory: "/.github/coderabbit-config" + schedule: + interval: "monthly" + labels: ["dependencies"] + # Keep the requirement EXACT. `widen` would turn the pin into a range, which + # `--require-hashes` rejects outright at install time — the job would go red + # in every enrolled repo rather than degrade quietly, but red-everywhere is + # still not a state to schedule for yourself. + versioning-strategy: "increase" + open-pull-requests-limit: 5 + cooldown: + # These run inside every consumer repo's CI, so let a release age before + # adopting it. Majors get longer: a jsonschema major can change validator + # semantics, which would silently change what this check MEANS — the unit + # suite asserts the verdicts, so such a bump should be read, not rubber- + # stamped. + default-days: 7 + semver-major-days: 14 + # Dependency-free today, but declared so the day a module is added it is # watched rather than silently rotting — the same failure mode this file # exists to fix. diff --git a/.github/workflows/bump-coderabbit-config-callers.yml b/.github/workflows/bump-coderabbit-config-callers.yml new file mode 100644 index 00000000..6b6ba4b1 --- /dev/null +++ b/.github/workflows/bump-coderabbit-config-callers.yml @@ -0,0 +1,161 @@ +name: Bump coderabbit-config-validate callers + +# When the coderabbit-config-validate reusable workflow (or the checker + vendored +# schema behind it) is updated on main, open a SHA-bump PR in every repo that pins +# a caller against it. PRs are opened by Cloud Code Bot so they are easy to filter +# and merge. +# +# This is a thin entrypoint over the shared bumper at +# .github/bump-callers/bump-callers.sh — the same script drives every other fleet. +# Keeping ONE implementation is deliberate: a forked copy is how other shared +# machinery in the org has drifted. The entrypoints differ only in their +# path-filter trigger and the parameters passed below. (They stay separate rather +# than one matrix because their triggers differ — a cursor-review.yml change must +# not spuriously bump these callers, and vice versa.) +# +# This fleet matters more than most for the SCHEMA, not the workflow file: the +# vendored schema.v2.json is what every consumer is graded against, and it moves +# on its own schedule via refresh-coderabbit-schema.yml. Without this fleet a +# refreshed schema would sit on main while every pinned caller kept validating +# against a months-old copy — the exact vendoring-rots failure the refresh job +# exists to prevent, reintroduced one layer down. +# +# The caller list is NOT hardcoded here. This repo is PUBLIC (workflow file and +# Actions run logs are both publicly viewable), and most callers are private, so +# their names must never appear in this file or its logs. The list lives in the +# repo-level Actions SECRET `CODERABBIT_CONFIG_CALLERS` as a JSON array of +# {"repo","file","label"} objects, same shape as the other fleets' rosters. +# +# A SECRET, not a variable (BE-6472): the roster reaches the script through the +# step's `env:` below, and Actions prints that env block BEFORE the step runs — so +# a variable's raw value would be published in this public repo's run log ahead of +# any masking the script could do. A secret is runner-masked everywhere, that dump +# included. `bump-callers.sh` still `::add-mask::`es every repo name before IT +# echoes anything: Actions masks the roster as ONE exact string, not each name +# inside it, so a name echoed on its own would otherwise print in the clear. +# +# The roster is seeded EMPTY, so `ALLOW_EMPTY: "true"` below: this fleet grows as +# callers land (v1 wires one repo; the rest follow), and an empty list is a clean +# no-op rather than an error. Flip it to "false" once the fleet has live callers — +# at that point an empty roster is a bug, and a silent clean exit would leave every +# caller pinned to a stale checker with nothing red anywhere to say so. +# +# Update flow — adding/removing a caller needs NO public commit: +# jq -c . callers.json | gh secret set CODERABBIT_CONFIG_CALLERS --repo Comfy-Org/github-workflows +# Keep the canonical callers.json in a PRIVATE infra/ops repo so roster edits have +# a reviewed source of truth; the org audit log records each edit. (The specific +# home repo is intentionally not named here — this file is public.) +# +# Recovery note: GitHub evaluates a `paths:` filter against only the first 300 +# changed files of a push, so a change here buried in a larger main push can +# create NO run at all. `workflow_dispatch` above is the recovery — run it once +# from main and the fleet catches up. Run it once when this fleet first lands, +# too: landing a fleet does not touch the reusable it watches, so its own merge +# matches no path filter and fires no run. + +on: + workflow_dispatch: {} # allow on-demand runs (e.g. to re-bump callers) + push: + branches: [main] + paths: + - .github/workflows/coderabbit-config-validate.yml + - .github/coderabbit-config/** + +permissions: + contents: read + +# Serialize runs of this fleet. The bumper pushes to a STABLE branch +# (ci/bump-coderabbit-config-validate) shared across runs, so two overlapping runs +# (a rapid second main push, or a push racing a manual re-run) would force-reset +# that branch and race the PR update — an older run finishing last could leave the +# committed diff pinned to a stale SHA. cancel-in-progress: false lets the running +# bump finish; GitHub keeps only the newest pending run, so the latest SHA always +# wins (BE-3882). +concurrency: + group: bump-coderabbit-config-callers + cancel-in-progress: false + +jobs: + bump: + # Guard against a workflow_dispatch run from a non-main ref: github.sha is the + # tip of whatever ref was selected, and the bumper force-resets a stable shared + # branch — a manual run from an older ref would pin every caller to a stale SHA + # (and run this job's script, with the App token minted below, from an + # unreviewed commit). The push trigger is already main-only, so this only ever + # skips stray manual runs. + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + # The job is a bounded loop of `git`/`gh` network calls, plus the preflight's + # deepening fetch; nothing here should take minutes. Without this a hung call + # would hold a runner for the default 6 hours (and, via the serializing + # concurrency group above, block every later bump behind it). + timeout-minutes: 20 + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + # The shared staleness/decommission guard — one implementation for every + # fleet, documented in .github/bump-callers/README.md "Preflight". It decides + # whether this run is a stale re-run (a later commit already touched the + # watched surface and has its own run) or the surface has been + # decommissioned, and emits the SHA the bump below pins. + # WATCHED/WATCHED_ASSETS are LITERAL paths, never the `paths:` globs, and + # must cover EVERY entry in this fleet's filter above: the re-point only pins + # callers to a tip whose watched content it compared, so widen these inputs + # in the same change if you ever widen that filter. + - name: Preflight (staleness / decommission guard) + id: preflight + env: + NEW_SHA: ${{ github.sha }} + WATCHED: .github/workflows/coderabbit-config-validate.yml + WATCHED_ASSETS: .github/coderabbit-config + run: bash .github/bump-callers/preflight.sh + + - name: Generate Cloud Code Bot token + # Stale run or decommissioned surface — don't mint an org-wide write token + # for a job that is about to bump nothing. + if: steps.preflight.outputs.proceed == 'true' + uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0 — pinned: see dependabot.yml ignore (v2+ breaks cross-repo `owner:` token scoping) + id: token + with: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.CLOUD_CODE_BOT_PRIVATE_KEY }} + # `owner:` with no `repositories:` is deliberate and cannot be narrowed: + # the caller list is a runtime secret (see the header), so the repos this + # token must reach are not knowable at authoring time — and naming them + # here would leak private caller names into a public file. The + # PERMISSIONS can be narrowed without naming anything, so they are: the + # bumper commits the rewritten caller file (contents), opens or updates + # the bump PR (pull-requests), and stamps the caller's label through the + # issues API (issues). + owner: Comfy-Org + permission-contents: write + permission-pull-requests: write + permission-issues: write + + - name: Bump SHA in caller repos + # Stale run or decommissioned surface — nothing to bump. + if: steps.preflight.outputs.proceed == 'true' + env: + GH_TOKEN: ${{ steps.token.outputs.token }} + # NOT github.sha: when main moved on but the watched surface is + # unchanged, the preflight re-points this run at the verified tip, and + # reading github.sha here would silently discard that re-point. + NEW_SHA: ${{ steps.preflight.outputs.new_sha }} + # Names the roster to fix in an error message. It is a SECRET, not a + # variable; the env key keeps the fleets' historical name so every + # entrypoint and the shared script stay in step. + VAR_NAME: CODERABBIT_CONFIG_CALLERS + TAG: coderabbit-config-validate + WORKFLOW_FILE: coderabbit-config-validate.yml + # An empty roster — `[]`, or a secret nobody has set — is a clean no-op + # here, not an error. See the header for when to flip this. + ALLOW_EMPTY: "true" + # JSON array of {"repo","file","label"} — see the header comment for the + # update flow. Kept in a repo-level SECRET (not this file, and not a + # variable) so private caller names never land in this public repo — nor, + # since a secret is masked in the step's env dump too, in its run logs. + CALLERS_JSON: ${{ secrets.CODERABBIT_CONFIG_CALLERS }} + run: bash .github/bump-callers/bump-callers.sh diff --git a/.github/workflows/coderabbit-config-validate.yml b/.github/workflows/coderabbit-config-validate.yml new file mode 100644 index 00000000..45b3a1f9 --- /dev/null +++ b/.github/workflows/coderabbit-config-validate.yml @@ -0,0 +1,202 @@ +name: CodeRabbit config validate (reusable) + +# Reusable workflow that validates the caller repo's `.coderabbit.yaml` against +# CodeRabbit's published config schema, so a broken config fails on the PR that +# breaks it. +# +# Why this needs a machine check. CodeRabbit rejects an invalid `.coderabbit.yaml` +# WHOLE: the entire file is discarded and the review runs on org-wide UI defaults +# instead, so every reviewer instruction, path filter, path instruction and +# WIP-skip rule in it goes silently inert. Nothing about the PR looks different — +# the file still reads fine, only the validator sees the loss. +# +# And the feedback is displaced by one PR: CodeRabbit validates the config on the +# BASE branch, not the PR head. The PR that breaks the file goes green, and the +# breakage first surfaces on the NEXT PR, attributed to a change that did not +# cause it. So the human loop here is not merely slow — it points at the wrong +# diff. (Two independent tickets fixed the same over-long `tone_instructions` +# field on the same repo within six days, which is the signature of a failure +# nothing detects.) +# +# It runs in the CALLER's context, so `actions/checkout` checks out the calling +# repo and the check operates on that repo's `.coderabbit.yaml`. The checker +# itself is loaded from THIS repo (public, pinned via `workflows_ref`) — never +# from the caller's checkout — so a PR cannot rewrite the check that judges it. +# +# SEVERITY IS SPLIT, and the split mirrors what CodeRabbit itself does: +# * YAML parse error / `maxLength` violation / type or enum error -> FAILS. +# These are what CodeRabbit rejects the whole file for. +# * unknown / additional property -> WARNS by default. CodeRabbit STRIPS a key +# it does not recognize rather than rejecting the file, so the config still +# loads while everything under that key silently does nothing. That is a real +# defect — a `tools:` block written at the document root instead of under +# `reviews:` inverts every setting in it, because the schema defaults are the +# opposite of what was written — but it is not file-rejecting, and failing on +# it would put several org repos red on day one. `strict_unknown_keys: true` +# escalates it for a repo that has cleaned up and wants to stay clean. +# +# There is deliberately NO `paths:` filter in the caller pattern below. A +# path-filtered check reports "skipped" rather than "success" on unrelated PRs, +# which makes it useless as a required status check. +# +# The schema is VENDORED (committed at .github/coderabbit-config/schema.v2.json) +# and never fetched at validation time: a live fetch would make every consumer's +# CI depend on a third-party endpoint, and an upstream tightening would turn CI +# red across the fleet with no change on our side. `refresh-coderabbit-schema.yml` +# in this repo watches upstream for drift and proposes the bump as a reviewable +# PR instead. +# +# Caller pattern (place in the consumer repo at +# .github/workflows/coderabbit-config-validate.yml): +# +# name: CodeRabbit config +# on: +# pull_request: +# push: +# branches: [main] +# jobs: +# coderabbit-config: +# permissions: +# contents: read +# uses: Comfy-Org/github-workflows/.github/workflows/coderabbit-config-validate.yml@ # v1 +# with: +# workflows_ref: # pin the checker to the same ref as `uses:` +# +# INPUTS: +# workflows_ref REQUIRED. Ref of Comfy-Org/github-workflows to load the +# checker from. Pin to the SAME commit SHA as `uses:`. +# config_file Path to the config to validate, relative to the repo +# root. Default `.coderabbit.yaml`. (A repo using the +# `.coderabbit.yml` spelling points this at it.) +# strict_unknown_keys Escalate an unknown/additional property from a warning +# to a failure. Default false. +# +# No secrets required. + +on: + workflow_call: + inputs: + config_file: + description: >- + Path to the CodeRabbit config to validate, relative to the repo root. + Default `.coderabbit.yaml`. A repo with no such file passes. + type: string + required: false + default: .coderabbit.yaml + strict_unknown_keys: + description: >- + Fail on an unknown/additional property instead of warning. Default + false — CodeRabbit strips unknown keys rather than rejecting the file, + so this is opt-in for a repo that has already cleaned up. + type: boolean + required: false + default: false + workflows_ref: + description: >- + REQUIRED. Ref of Comfy-Org/github-workflows to load the checker and the + vendored schema from. Must be the SAME commit SHA you pin `uses:` to — + otherwise the workflow is pinned but the code it runs is not. There is + deliberately no default: a floating `main` default would silently load + a mutable checker. + type: string + required: true + +permissions: + contents: read + +jobs: + check: + name: CodeRabbit config validate + runs-on: ubuntu-latest + permissions: + contents: read + # A YAML parse plus a schema walk over a file measured in kilobytes. Anything + # approaching this bound is a hung network call in `pip install`, not work. + timeout-minutes: 10 + steps: + - name: Checkout caller repo + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Require a pinned workflows_ref + # workflows_ref has no default on purpose. GitHub does NOT enforce + # `required: true` for workflow_call inputs, so an omitted input arrives + # as '' and actions/checkout would silently fall back to this repo's + # default branch — running MUTABLE scripts under a pin that claims + # otherwise. Fail fast instead. (BE-5546) + env: + WORKFLOWS_REF: ${{ inputs.workflows_ref }} + run: | + # actions/checkout reads `ref` through core.getInput, which TRIMS, so a + # whitespace-only value is an empty ref to IT while sailing past a bare + # -z test here. Compare the stripped form, and echo only that: dropping + # newlines also stops a multi-line value from smuggling a ::workflow + # command:: into the log, and from satisfying the line-oriented grep + # below on one 40-hex line among many. + REF="$(printf '%s' "$WORKFLOWS_REF" | tr -d '[:space:]')" + if [ -z "$REF" ]; then + echo "::error::workflows_ref is required; pin it to the same commit SHA as the uses: line (see header example)" + exit 1 + fi + if ! printf '%s' "$REF" | grep -Eq '^[0-9a-f]{40}$'; then + echo "::warning::workflows_ref '$REF' is not a full 40-hex commit SHA — branch and tag refs are mutable and can skew between jobs mid-run" + fi + + - name: Load the checker and the vendored schema + # Both come from THIS repo at the pinned ref, never from the caller's + # checkout, so a PR can't rewrite the check — nor swap the schema it is + # graded against, which would be the quieter version of the same bypass. + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: Comfy-Org/github-workflows + ref: ${{ inputs.workflows_ref }} + path: _coderabbit_config + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.12' + + - name: Install the pinned validator dependencies + # `--require-hashes` makes pip refuse any artifact whose bytes differ from + # the ones reviewed in requirements.txt. The wheels pinned there are the + # cp312 / manylinux x86_64 set matching the runner + interpreter above; a + # mismatch fails LOUDLY rather than silently falling back to an unhashed + # artifact, which is the point of the flag. + # + # This is the one place this otherwise stdlib-only repo takes a Python + # dependency, and both halves are unavoidable: there is no YAML parser in + # the standard library, and the whole value of the check is reproducing + # the verdict CodeRabbit's own Draft 2020-12 validator reaches. See the + # header of requirements.txt. + # + # `-P` is load-bearing, not tidiness. This step's working directory is the + # CALLER's checkout — i.e. the untrusted PR head — and `python3 -m pip` + # normally puts that directory FIRST on sys.path. A PR adding a top-level + # `pip/__main__.py` would therefore run its own code here, before the + # pinned checker ever starts, and could rewrite `_coderabbit_config/` so + # the tamper-proof validator grades the PR with the PR's own logic. `-P` + # (PYTHONSAFEPATH, 3.11+; the runner is pinned to 3.12 above) suppresses + # that prepend. The checker step below does not need it: running a script + # by path puts the SCRIPT's directory on sys.path, which is the pinned + # checkout, never the workspace. + run: | + python3 -P -m pip install --disable-pip-version-check --no-input \ + --require-hashes --only-binary=:all: \ + -r "$GITHUB_WORKSPACE/_coderabbit_config/.github/coderabbit-config/requirements.txt" + + - name: Validate .coderabbit.yaml + env: + CODERABBIT_CHECK_ROOT: ${{ github.workspace }} + CODERABBIT_CONFIG_FILE: ${{ inputs.config_file }} + STRICT_UNKNOWN_KEYS: ${{ inputs.strict_unknown_keys }} + run: | + # --root is the caller's checkout (the workspace root); the checker and + # the vendored schema beside it come from _coderabbit_config/, i.e. the + # pinned ref. Keep those two sources distinct — resolving the schema + # relative to --root is exactly how a PR would grade itself. + python3 "$GITHUB_WORKSPACE/_coderabbit_config/.github/coderabbit-config/check_coderabbit_config.py" \ + --root "$CODERABBIT_CHECK_ROOT" \ + --config "$CODERABBIT_CONFIG_FILE" diff --git a/.github/workflows/refresh-coderabbit-schema.yml b/.github/workflows/refresh-coderabbit-schema.yml new file mode 100644 index 00000000..959764f7 --- /dev/null +++ b/.github/workflows/refresh-coderabbit-schema.yml @@ -0,0 +1,279 @@ +name: Refresh CodeRabbit schema + +# Keep the vendored CodeRabbit config schema from going stale silently. +# +# `coderabbit-config-validate.yml` validates against a VENDORED copy of +# CodeRabbit's schema (.github/coderabbit-config/schema.v2.json) rather than +# fetching it live: a live fetch would make every consumer's CI depend on a +# third-party endpoint, and an upstream tightening would turn CI red across the +# fleet with no change on our side. The cost of vendoring is that the copy rots — +# nothing moves it, so the check would keep grading configs against an +# ever-older schema until someone noticed. This job notices instead: weekly it +# fetches the published schema, compares it SEMANTICALLY with the vendored copy, +# and when they differ opens a PR moving the vendored file with a summary of what +# changed. Nothing auto-merges — a human reads the summary, which is the point. +# +# Merging that PR touches .github/coderabbit-config/**, which is exactly the path +# filter bump-coderabbit-config-callers.yml watches, so the SHA-pinned caller +# fleet rolls forward on its own. No new fleet plumbing here. +# +# Modelled on bump-cursor-cli-pin.yml: same main-only job guard, same +# non-cancelling concurrency around a stable shared branch, same App-token +# credential pattern (vars.APP_ID + secrets.CLOUD_CODE_BOT_PRIVATE_KEY, already +# provisioned in this repo). +# +# The fetch uses `curl -fsSL`, and the -L is load-bearing: the schema URL +# 301-redirects, and a bare `curl` writes a small HTML redirect stub instead. That +# stub is neither JSON nor a schema — `schema_drift.py` refuses it with exit 2 +# rather than reporting "no drift", because a check that silently freezes is worse +# than one that fails. + +on: + schedule: + # Mondays 15:00 UTC — an hour after bump-cursor-cli-pin so the two weekly + # PR-opening jobs don't collide on the same runner minute, and early enough + # in the week that a drift PR gets read before the weekend. + - cron: '0 15 * * 1' + workflow_dispatch: {} + +permissions: + contents: read + +# Serialize runs: the refresh lands on a STABLE branch +# (ci/refresh-coderabbit-schema) that is force-reset each run, so two overlapping +# runs (a manual dispatch racing the cron) would race that reset and the PR +# update, and the older run finishing last could leave the PR carrying a stale +# schema. cancel-in-progress: false lets the running refresh finish; the newest +# pending run then wins. Same reasoning as the bump fleets (BE-3882). +concurrency: + group: refresh-coderabbit-schema + cancel-in-progress: false + +jobs: + refresh: + # Guard against a workflow_dispatch run from a non-main ref: this job + # force-resets a shared branch and mints an App token, so it must only ever + # run from reviewed main. The schedule trigger is already main-only, so this + # only skips stray manual runs. + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + timeout-minutes: 15 + env: + SCHEMA_URL: https://coderabbit.ai/integrations/schema.v2.json + VENDORED: .github/coderabbit-config/schema.v2.json + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # `ref: main` resolves at run time, so the refresh is always built on + # the LIVE main tip. Without it a re-run of an older run would check out + # that run's (now stale) github.sha, and the force-push below would + # publish a branch that reverts everything merged since. The `if:` guard + # above already restricts this job to main. + ref: main + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.12' + + - name: Fetch the published schema + run: | + set -euo pipefail + # -L is load-bearing: the URL 301-redirects, and without it curl writes + # a ~167-byte HTML redirect stub that parses as neither JSON nor a + # schema. -f turns an HTTP error into a non-zero exit rather than a body + # we would happily vendor. The remaining flags mirror the hardening in + # bump-cursor-cli-pin.yml: https only (including across the redirect), + # bounded time, bounded size, bounded retries. + curl -fsSL \ + --proto '=https' --proto-redir '=https' \ + --connect-timeout 10 --max-time 60 \ + --retry 3 --retry-all-errors --retry-delay 2 --retry-max-time 120 \ + --max-filesize 8388608 \ + "$SCHEMA_URL" -o "${RUNNER_TEMP}/schema.v2.json" + + - name: Compare against the vendored copy + id: drift + run: | + set -uo pipefail + summary="${RUNNER_TEMP}/drift.md" + set +e + python3 .github/coderabbit-config/schema_drift.py \ + --vendored "$VENDORED" \ + --fetched "${RUNNER_TEMP}/schema.v2.json" \ + --summary-out "$summary" + code=$? + set -e + case "$code" in + 0) + echo "drifted=false" >> "$GITHUB_OUTPUT" + echo "Vendored CodeRabbit schema is current." >> "$GITHUB_STEP_SUMMARY" + ;; + 1) + echo "drifted=true" >> "$GITHUB_OUTPUT" + ;; + *) + # Exit 2 is "I could not compare" — an unreadable or non-schema + # fetch. Fail the run: a comparison we could not perform is not + # evidence that nothing changed, and swallowing it here is how a + # vendored file freezes forever behind a green weekly run. + echo "::error::Could not compare the fetched schema against the vendored copy (schema_drift.py exit ${code})." + exit 1 + ;; + esac + + - name: Vendor the new schema and re-run the checker against it + id: invariants + if: steps.drift.outputs.drifted == 'true' + run: | + set -euo pipefail + cp "${RUNNER_TEMP}/schema.v2.json" "$VENDORED" + + python3 -m pip install --disable-pip-version-check --no-input \ + --require-hashes --only-binary=:all: \ + -r .github/coderabbit-config/requirements.txt + + # The proposed schema has to still work as the thing the fleet is graded + # against. The unit suite asserts the facts the checker's messages rest + # on (root closed, tone_instructions capped at 250, `tools` living under + # `reviews`, the 14-cap set), so a refresh that would quietly redefine + # what the check MEANS must not merge green. Plus a self-check: this repo + # has no .coderabbit.yaml, so validate a smoke fixture rather than nothing. + # + # CAPTURED, not fatal — and that distinction is the whole point. Those + # assertions are exact (`len(caps) == 14`, `tone_instructions == 250`), so + # ANY legitimate upstream cap add, removal or change fails them. Aborting + # this step would take every later step with it, since their + # `if: steps.drift.outputs.drifted == 'true'` carries an implicit + # success() — so no PR would be opened, and the drift class this workflow + # exists to catch first would be the one it silently never proposes. + # Instead the verdict rides in the PR body and reddens the run at the end, + # once there is a PR to explain it. + log="${RUNNER_TEMP}/invariants.log" + set +e + ( + set -e + python3 -m unittest discover -s .github/coderabbit-config/tests -p 'test_*.py' + root="$(mktemp -d)" + printf 'language: en-US\nreviews:\n profile: chill\n' > "$root/.coderabbit.yaml" + python3 .github/coderabbit-config/check_coderabbit_config.py --root "$root" + ) > "$log" 2>&1 + code=$? + set -e + cat "$log" + + if [ "$code" -eq 0 ]; then + echo "invariants=pass" >> "$GITHUB_OUTPUT" + else + echo "invariants=fail" >> "$GITHUB_OUTPUT" + echo "::warning::The invariant suite fails against the proposed schema (exit ${code}). Opening the refresh PR anyway so the change is reviewable; this run ends red." + fi + + - name: Generate Cloud Code Bot token + id: token + if: steps.drift.outputs.drifted == 'true' + uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0 — pinned: see dependabot.yml ignore (v2+ breaks cross-repo `owner:` token scoping) + with: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.CLOUD_CODE_BOT_PRIVATE_KEY }} + # No `owner:` — this only ever writes to THIS repo, so the default + # repo-scoped installation token is both sufficient and narrower. + permission-contents: write + permission-pull-requests: write + + - name: Open or update the refresh PR + if: steps.drift.outputs.drifted == 'true' + env: + GH_TOKEN: ${{ steps.token.outputs.token }} + BRANCH: ci/refresh-coderabbit-schema + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + INVARIANTS: ${{ steps.invariants.outputs.invariants }} + run: | + set -euo pipefail + + # Verify the body's ingredients BEFORE the force-push. The push moves a + # shared branch; if drift.md were missing, the `cat` below would abort + # under `set -e` with the branch already reset and no PR to explain it. + if [ ! -s "${RUNNER_TEMP}/drift.md" ]; then + echo "::error::Drift was reported but ${RUNNER_TEMP}/drift.md is missing or empty — refusing to reset the shared branch with nothing to explain it." + exit 1 + fi + + # Committer identity is cosmetic — the PR AUTHOR (what reviewers and + # filters key off) comes from the App token used below. Same convention + # as bump-cursor-cli-pin.yml and groom.yml's auto-builder. + git config user.name 'coderabbit-schema refresher' + git config user.email 'coderabbit-schema-refresher@users.noreply.github.com' + git checkout -B "$BRANCH" + git add "$VENDORED" + git commit -m "ci(coderabbit-config): refresh the vendored CodeRabbit schema" + + # Force-reset the stable branch so its diff is rebuilt from the current + # main tip rather than stacked on a previous week's refresh. The token is + # masked in the run log by the create-github-app-token action. + git push --force \ + "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \ + "HEAD:refs/heads/${BRANCH}" + + # Built with printf rather than a heredoc: a heredoc terminator has to + # sit at column 0, which would end this YAML block scalar early. + body="$(mktemp "${RUNNER_TEMP}/pr-body.XXXXXX")" + # SC2016: the single-quoted literals hold Markdown backticks, not + # command substitutions — that is exactly why they are single-quoted. + # shellcheck disable=SC2016 + { + printf '%s\n\n' 'Upstream'"'"'s CodeRabbit config schema has drifted from the copy vendored here, which is what `coderabbit-config-validate.yml` grades every enrolled repo against.' + cat "${RUNNER_TEMP}/drift.md" + printf '\n' + printf '%s\n\n' '**Before merging**, check the tightened-cap section above if there is one: a lowered `maxLength` retroactively invalidates configs nobody has touched, and merging this makes their next PR red. Landing the cleanup alongside is usually the right order.' + if [ "${INVARIANTS:-}" = "fail" ]; then + # No blank line between the marker and the body: GitHub only + # renders the alert when the blockquote is contiguous. + printf '%s\n' '> [!WARNING]' + printf '%s\n\n' '> **The invariant unit suite FAILS against the proposed schema** ([this run]('"$RUN_URL"')). That suite asserts the exact facts the checker'"'"'s messages rest on, so this is the signal to read closely, not a flake: either the schema change is one we must adapt the checker and its tests to, or the fetch is not what we think it is. Update those assertions in this PR, deliberately, before merging.' + printf '%s\n' '
Invariant suite output' + printf '\n```\n' + tail -n 60 "${RUNNER_TEMP}/invariants.log" || echo '(invariant log unavailable)' + printf '```\n\n
\n\n' + else + printf '%s\n\n' 'The unit suite ran green against the proposed schema in [this run]('"$RUN_URL"') — it asserts the facts the checker'"'"'s messages rest on, so a refresh that would silently redefine the check cannot slip through unnoticed.' + fi + printf '%s\n\n' 'Merging this touches `.github/coderabbit-config/**`, which triggers `bump-coderabbit-config-callers.yml` and rolls the SHA-pinned caller fleet forward.' + printf '%s\n' '_Opened by the `refresh-coderabbit-schema` workflow._' + } > "$body" + + # Reuse the one open PR for this branch if there is one — the force-push + # already refreshed its diff, so only the title/body need updating. The + # stable head branch guarantees at most one. Exclude cross-repository + # PRs: `--head` matches by branch NAME across forks, and this branch name + # is predictable, so a fork PR opened on it must not be mistaken for ours + # and stamped with the official text. + existing=$(gh pr list --repo "${GITHUB_REPOSITORY}" --head "$BRANCH" --state open \ + --json number,isCrossRepository \ + --jq 'map(select(.isCrossRepository == false)) | .[0].number // empty') + + title='ci(coderabbit-config): refresh the vendored CodeRabbit schema' + if [ -n "$existing" ]; then + gh pr edit "$existing" --repo "${GITHUB_REPOSITORY}" --title "$title" --body-file "$body" + echo "Updated PR #${existing}" + else + gh pr create --repo "${GITHUB_REPOSITORY}" \ + --head "$BRANCH" --base main \ + --title "$title" --body-file "$body" + fi + + { + echo "Vendored CodeRabbit schema drift proposed:" + echo + cat "${RUNNER_TEMP}/drift.md" + } >> "$GITHUB_STEP_SUMMARY" + + - name: Fail the run when the proposed schema breaks the invariants + # Deliberately last: the PR is already open and carries the failure in its + # body, so the red run points at something reviewable instead of vanishing. + if: steps.invariants.outputs.invariants == 'fail' + run: | + echo "::error::The proposed schema fails the checker's invariant suite. The refresh PR is open with the output in its body — adapt the checker and its assertions there, deliberately." + exit 1 diff --git a/.github/workflows/test-coderabbit-config-validate.yml b/.github/workflows/test-coderabbit-config-validate.yml new file mode 100644 index 00000000..2f19a7f4 --- /dev/null +++ b/.github/workflows/test-coderabbit-config-validate.yml @@ -0,0 +1,190 @@ +name: Test coderabbit-config-validate script + +# Runs the unit tests for the .coderabbit.yaml validator plus CLI smoke tests +# that exercise each severity path end-to-end. The checker gates every consumer +# repo's CI, so a regression here silently breaks their required status check — +# and, worse for this particular check, a regression that makes it pass +# everything is invisible: a validator that never fails looks exactly like a +# fleet with no broken configs. Hence the smoke tests assert the FAILING +# directions too, not just that a good config passes. + +on: + pull_request: + paths: + - '.github/coderabbit-config/**' + - '.github/workflows/test-coderabbit-config-validate.yml' + - '.github/workflows/coderabbit-config-validate.yml' + push: + branches: [main] + paths: + - '.github/coderabbit-config/**' + - '.github/workflows/test-coderabbit-config-validate.yml' + - '.github/workflows/coderabbit-config-validate.yml' + +permissions: + contents: read + +concurrency: + group: test-coderabbit-config-validate-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: unittest + smoke + runs-on: ubuntu-latest + timeout-minutes: 10 + env: + CHECK: .github/coderabbit-config/check_coderabbit_config.py + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.12' + + - name: Install the pinned validator dependencies + # The same `--require-hashes` install the reusable workflow performs, so + # a requirements.txt whose hashes or transitive set are wrong fails HERE, + # on the PR that broke it, rather than in every consumer's CI after merge. + run: | + python3 -m pip install --disable-pip-version-check --no-input \ + --require-hashes --only-binary=:all: \ + -r .github/coderabbit-config/requirements.txt + + - name: Run coderabbit-config unit tests + run: python3 -m unittest discover -s .github/coderabbit-config/tests -p 'test_*.py' -v + + - name: Smoke test — a valid config passes + run: | + root="$(mktemp -d)" + cat > "$root/.coderabbit.yaml" <<'YAML' + language: en-US + tone_instructions: Be concise and concrete. + reviews: + profile: chill + tools: + golangci-lint: + enabled: false + YAML + python3 "$CHECK" --root "$root" + + - name: Smoke test — an absent config passes and says so + run: | + root="$(mktemp -d)" + out="$(python3 "$CHECK" --root "$root")" + echo "$out" + # The log line is the contract: "no config here" must never read the + # same as "config validated clean". + echo "$out" | grep -q 'nothing to validate' + echo "$out" | grep -q 'absent' + + - name: Smoke test — the other spelling is validated, not reported absent + run: | + # CodeRabbit honours .coderabbit.yml as well. A repo on that spelling + # that leaves config_file at its default must not get a permanently + # green check over a config nobody looked at. + root="$(mktemp -d)" + python3 -c "open('$root/.coderabbit.yml','w').write('tone_instructions: ' + 'x'*300 + chr(10))" + if out="$(python3 "$CHECK" --root "$root")"; then + echo "::error::checker reported a pass while an invalid .coderabbit.yml sat beside the default name" + echo "$out" + exit 1 + fi + echo "$out" + echo "$out" | grep -q '::warning::' + echo "$out" | grep -q '.coderabbit.yml' + + - name: Smoke test — a config symlinked out of the tree is refused, not read + run: | + # abspath does not resolve symlinks but open() follows them, so without + # a realpath containment check the TARGET's content reaches this public + # log through the YAML error message. + root="$(mktemp -d)" + outside="$(mktemp -d)" + printf 'this: [is not: valid yaml\n' > "$outside/secret.yaml" + ln -s "$outside/secret.yaml" "$root/.coderabbit.yaml" + set +e + out="$(python3 "$CHECK" --root "$root")" + code=$? + set -e + echo "$out" + if [ "$code" != "2" ]; then + echo "::error::expected exit 2 for a config resolving outside the repo root, got ${code}" + exit 1 + fi + echo "$out" | grep -q 'outside the checked-out repo root' + + - name: Smoke test — an over-long tone_instructions fails + run: | + root="$(mktemp -d)" + python3 -c "open('$root/.coderabbit.yaml','w').write('tone_instructions: ' + 'x'*300 + chr(10))" + if out="$(python3 "$CHECK" --root "$root")"; then + echo "::error::checker passed an over-long tone_instructions — expected a non-zero exit" + echo "$out" + exit 1 + fi + echo "$out" + # Actual vs permitted length, both named — that is what makes the + # annotation actionable without opening the schema. + echo "$out" | grep -q '300 characters' + echo "$out" | grep -q '250' + + - name: Smoke test — a misplaced top-level `tools` block warns, then fails under strict + run: | + root="$(mktemp -d)" + cat > "$root/.coderabbit.yaml" <<'YAML' + reviews: + profile: chill + tools: + # Project uses go vet + staticcheck, not golangci-lint + golangci-lint: + enabled: false + YAML + out="$(python3 "$CHECK" --root "$root")" # must NOT fail by default + echo "$out" + echo "$out" | grep -q '::warning ' + echo "$out" | grep -q 'unknown key `tools`' + echo "$out" | grep -q 'reviews.tools' + + if out="$(python3 "$CHECK" --root "$root" --strict-unknown-keys)"; then + echo "::error::strict_unknown_keys did not fail a misplaced top-level tools block" + echo "$out" + exit 1 + fi + echo "$out" + echo "$out" | grep -q '::error ' + + - name: Smoke test — malformed YAML fails + run: | + root="$(mktemp -d)" + printf 'reviews:\n profile: chill\n path_filters:\n - "x"\n' > "$root/.coderabbit.yaml" + if out="$(python3 "$CHECK" --root "$root")"; then + echo "::error::checker passed a malformed YAML file — expected a non-zero exit" + echo "$out" + exit 1 + fi + echo "$out" + echo "$out" | grep -q 'not valid YAML' + + - name: Smoke test — an unusable schema exits 2, not 0 + run: | + # The redirect-stub case: the schema URL 301-redirects and a `curl` + # without -L writes a 167-byte HTML stub. "I could not run the check" + # must never exit like "the config is fine". + root="$(mktemp -d)" + stub="$(mktemp)" + printf 'Moved' > "$stub" + printf 'language: en-US\n' > "$root/.coderabbit.yaml" + set +e + python3 "$CHECK" --root "$root" --schema "$stub" + code=$? + set -e + if [ "$code" != "2" ]; then + echo "::error::expected exit 2 for an unusable schema, got ${code}" + exit 1 + fi + echo "checker correctly refused to validate against a non-schema" diff --git a/AGENTS.md b/AGENTS.md index ac397ce8..2a853b32 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,8 +10,10 @@ themselves plus the scripts that back them. ## Commands -Python is stdlib-only (no requirements file); CI uses **Python 3.12**. Run from -the repo root. Each command mirrors a CI job (see `.github/workflows/test-*.yml`): +Python is stdlib-only, with ONE exception — `.github/coderabbit-config/`, which +needs a YAML parser and a real JSON Schema validator and pins both in +`requirements.txt` (exact versions + sha256, installed `--require-hashes`). +CI uses **Python 3.12**. Run from the repo root. Each command mirrors a CI job (see `.github/workflows/test-*.yml`): ```bash # cursor-review helper-script tests (extract-findings, post-review) @@ -39,6 +41,10 @@ bash scripts/pr-derisk/tests/test_plan_derisk.sh # workflow-pins lint (no reusable workflow may default `workflows_ref`) + its tests python3 -m unittest discover -s .github/workflow-pins/tests -p 'test_*.py' && python3 .github/workflow-pins/check_workflow_pins.py +# coderabbit-config validator tests (needs the pinned deps below; venv recommended) +python3 -m pip install --require-hashes --only-binary=:all: -r .github/coderabbit-config/requirements.txt +python3 -m unittest discover -s .github/coderabbit-config/tests -p 'test_*.py' -v + # AGENTS.md integrity checker against any repo tree python3 .github/agents-md-integrity/check_agents_md.py --root . ``` @@ -79,6 +85,13 @@ tests — run the matching command above for whatever you touched. one Dependabot-visible home of the `@anthropic-ai/claude-code` pin, which `groom.yml`'s gate reads once and feeds to all three agent jobs. Keep it exact; never re-hardcode a version in a `run:` step. Tests in `tests/`. +- `.github/coderabbit-config/` — `check_coderabbit_config.py` + the VENDORED + `schema.v2.json` behind `coderabbit-config-validate.yml`, plus `schema_drift.py` + (the comparison behind the weekly `refresh-coderabbit-schema.yml`). The schema is + vendored, never fetched at validation time: a live fetch makes every consumer's + CI depend on a third party, and an upstream tightening would redden the fleet with + no change here. `requirements.txt` is the repo's only Python dependency set — see + Commands. Tests in `tests/`. - `.github/refresh-reviewers/` — `generate.py`, the engine behind `refresh-reviewers.yml`: recomputes a caller's reviewers.yml from git history and rewrites just the reviewer lists for a drift PR. Tests in `tests/`. @@ -127,6 +140,20 @@ tests — run the matching command above for whatever you touched. command because `issue_comment` runs from the default branch, the commenter is association-gated, and no PR code is checked out. - `agents-md-integrity.yml` — enforces the AGENTS.md standard on the caller repo. +- `coderabbit-config-validate.yml` — validates the caller's `.coderabbit.yaml` + against the vendored CodeRabbit schema, on the PR that breaks it. CodeRabbit + rejects an invalid config WHOLE (everything in it goes inert) and validates the + BASE branch, so the breakage otherwise surfaces one PR late on the wrong diff. + Parse/`maxLength`/type errors FAIL; an unknown key WARNS (only where the schema + CLOSES the object) unless `strict_unknown_keys: true`; an absent file passes, + though the other extension spelling is validated, not called absent. A SIBLING of + agents-md-integrity, deliberately not an extension of it — that workflow is + scoped to agent-instruction files, and folding this in would push a Python + dependency and a new failure mode onto every one of its callers. +- `refresh-coderabbit-schema.yml` — weekly PR moving the vendored + `schema.v2.json` when upstream drifts (fetch is `curl -fsSL`; the URL + 301-redirects and a bare curl writes an HTML stub). Merging it trips the + coderabbit-config fleet, which rolls the callers. - `assign-reviewers.yml` — expertise-aware, load-balanced reviewer requests. - `refresh-reviewers.yml` — scheduled drift-detector: recomputes the caller's reviewers.yml from git history and opens one idempotent drift PR (never a @@ -140,7 +167,8 @@ tests — run the matching command above for whatever you touched. `bump-agents-md-callers.yml` / `bump-pr-size-callers.yml` / `bump-pr-risk-callers.yml` / `bump-pr-derisk-callers.yml` / `bump-assign-reviewers-callers.yml` / - `bump-groom-callers.yml` / `bump-detect-unreviewed-merge-callers.yml` — thin + `bump-groom-callers.yml` / `bump-detect-unreviewed-merge-callers.yml` / + `bump-coderabbit-config-callers.yml` — thin entrypoints over `bump-callers.sh` that fan SHA bumps out to consumers. A groom, pr-risk or pr-derisk caller pins TWICE (`uses:` + `workflows_ref:`); the shared rewrite moves both, so never hand-bump one alone. `stale.yml` and @@ -162,7 +190,7 @@ tests — run the matching command above for whatever you touched. repo **secrets** — one per fleet (`CURSOR_REVIEW_CALLERS`, `AUTO_LABEL_CALLERS`, `AGENTS_MD_CALLERS`, `PR_SIZE_CALLERS`, `PR_RISK_CALLERS` (SHARED by the pr-risk + pr-derisk fleets via `FILE_FILTER` — one entry per caller file, never a second roster), `ASSIGN_REVIEWERS_CALLERS`, `GROOM_CALLERS`, - `DETECT_UNREVIEWED_MERGE_CALLERS`; the bump-callers README table is canonical) + `DETECT_UNREVIEWED_MERGE_CALLERS`, `CODERABBIT_CONFIG_CALLERS`; the bump-callers README table is canonical) — never hardcoded in a workflow file or printed to run logs (logs are public). Secrets, not variables (BE-6472): a variable passed via a step's `env:` prints unmasked in the env dump Actions emits *before* the step, so the bumper's own diff --git a/README.md b/README.md index d7e8d3e1..0b091e62 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ complete, copy-pasteable caller. | [`stale.yml`](.github/workflows/stale.yml) | Stale-PR sweeper (`actions/stale`) plus a Slack digest of what it touched. PRs inactive for N days are labeled `stale`; still-inactive PRs are closed. The digest header names the source repo so batches from different repos posted to the same channel are unambiguous. Thresholds, messages, exempt labels, and the Slack channel are inputs; the caller owns the schedule + dry-run toggle. The calling job needs `pull-requests: write` and `issues: write`. Optional `SLACK_BOT_TOKEN`. | [stale.md](docs/callers/stale.md) | | [`groom.yml`](.github/workflows/groom.yml) | Scheduled/dispatch org-wide **code-cleanup sweep** (finds only — no commits, no PRs, never merges). A read-only FINDER agent scans a clean default-branch checkout (whole-repo, not a diff) for high-value refactors; an INDEPENDENT VERIFIER agent (fresh session) re-checks each as CONFIRM/DOWNGRADE/REJECT with a stable dedup signature; survivors are deduped against a durable GitHub-issue-state ledger and filed as `groom`-labeled GitHub issues (security-adjacent ones get `groom-security` — investigate, don't auto-implement). Mirrors the cursor-review topology: briefs + ledger live in [`.github/groom/`](.github/groom) as the single source of truth. The finder/verifier/builder agent jobs invoke the Claude CLI directly and mint no GitHub token, so they need nothing beyond `contents: read`; filing runs in a separate job as the bot you configure via `bot_app_id` (Comfy: cloud-code-bot). `dry_run` reports what it would file without opening issues. Runs on a **daily base cron** with a runtime cadence gate: set repo Actions variable `GROOM_INTERVAL_DAYS` (default 7 = weekly) to retune how often a real run happens — weekly → every-3-days → daily — with no workflow-file edit; a tick within the interval no-ops before the finder (`workflow_dispatch` bypasses the interval gate, but the volume gate — when the caller leaves it on — still applies). The calling job must grant `contents: read` + `issues: write` + `pull-requests: read` + `actions: read` — the first three are declared by the `file` / `build_select` jobs (needed even with `bot_app_id` set), and the interval gate needs `actions: read` (reads run history for the last real run); GitHub rejects a shorter grant at startup. Requires `ANTHROPIC_API_KEY` (+ `BOT_APP_PRIVATE_KEY` when `bot_app_id` is set). **Opt-in auto-builder** (`builder: true`, BE-4003): the top `max_prs` (default 5) CONFIRMED, non-security findings become **review-gated PRs** (full CI + cursor-review, **never auto-merged**) instead of issues; a credential-free `build` job emits only a patch artifact and a separate `build_pr` job opens the PR as the bot, preserving the security boundary. The ledger's PR-state (open/merged/closed) stops a built finding being re-proposed. **Path scoping** (`path`, BE-4757): scope a run to ONE directory (`path: services/api`) instead of the whole repo — empty (the default) is today's whole-repo behavior, byte-for-byte, so existing callers are unaffected. It CONSTRAINS rather than instructs (unlike `scope_desc`, which is prompt prose): the path is validated (absolute / `..`-component / escaping paths rejected) and contained against the checkout before any agent runs, the finder is handed the concrete in-scope file list, and findings whose evidence lies entirely outside the directory are dropped with the count logged. The checkout stays **full** on purpose — a refactor in `services/api` legitimately references `common/`. The cadence clock is **per scope** (the finder job is renamed `Audit — finder (scoped: )`, and the interval gate counts only prior runs of the same scope), so a scoped run leaves the next scheduled whole-repo tick due while a permanently scoped caller still gets a real `interval_days` cadence of its own; and the dedup signature ignores `path`, so a scoped run and a whole-repo run suppress each other's duplicates. Expose it as a `workflow_dispatch` input in the caller for on-demand scoped runs, or pin one in `with:` for a permanently scoped monorepo caller. Requires `bot_app_id`. `max_prs` is typed **`string`**, not `number`, so a caller can forward its own `workflow_dispatch` input straight through (`max_prs: ${{ github.event.inputs.max_prs \|\| '1' }}`) and let an operator raise the ceiling for one manual run — no `fromJSON()` cast in the caller, and the parse/clamp (empty → default, non-numeric → 0 PRs + warning, never a failed run) happens once inside the reusable. A build that cannot become a PR (patch over `pr_size_limit`, patch touching CI-privileged paths) **bails** to a `groom` issue so the paid-for work isn't lost — that path lives in `build_pr`, so **`max_findings` does not cap it** and `max_findings: 0` alone does not silence it; set `bail_sink: none` (an operational knob, so `GROOM_CONFIG` can set it with no PR) to file nothing and get a run-log warning + summary line instead. | [groom.md](docs/callers/groom.md) | | [`agents-md-integrity.yml`](.github/workflows/agents-md-integrity.yml) | Enforces the Comfy `AGENTS.md` standard on the caller repo: a top-level `AGENTS.md` must exist and stay under a hard line ceiling (`max_lines`, default 200; warns over `warn_lines`, default 150), a `CLAUDE.md` (if present) must be a thin `@AGENTS.md` shim rather than a divergent copy, no legacy `.cursorrules` (gated `forbid_cursorrules`), every nested monorepo `AGENTS.md` needs a sibling `@AGENTS.md` shim and to be under the ceiling (gated `check_nested`), and `AGENTS.md` should have a CODEOWNERS DRI (`require_codeowners`, warn-only by default). `exclude_paths` (newline-/comma-separated globs, default empty) carves payload subtrees — a repo whose product IS agent instructions, e.g. a plugin marketplace shipping `plugins/**/AGENTS.md` + a real `CLAUDE.md` — out of the nested scan without the all-or-nothing `check_nested: false`; exclusions are applied during the walk (never scanned or line-counted), reported in the log as `EXCLUDED: (matched )`, and a glob that would exclude the ROOT `AGENTS.md`/`CLAUDE.md` — or the whole tree without saying so (`/`, `*`, `*/**`) — is rejected (exit 2). Fails with a non-zero exit + GitHub annotations so it wires in as a required status check. The checker lives in [`.github/agents-md-integrity/`](.github/agents-md-integrity) (pin `workflows_ref` to the same ref as `uses:`); no secrets required. | [agents-md-integrity.md](docs/callers/agents-md-integrity.md) | +| [`coderabbit-config-validate.yml`](.github/workflows/coderabbit-config-validate.yml) | Validates the caller repo's `.coderabbit.yaml` against CodeRabbit's config schema, **on the PR that breaks it**. CodeRabbit rejects an invalid config *whole* — it discards the file and reviews with org-wide UI defaults, so every reviewer instruction, path filter and path instruction in it goes silently inert — and it validates the **base** branch, not the PR head, so the breakage first surfaces on the *next* PR, blamed on a change that did not cause it. Severity mirrors CodeRabbit's own behaviour: a YAML parse error, a `maxLength` violation or a type/enum error **fails**; an unknown/additional property **warns** (CodeRabbit strips those rather than rejecting the file, so the config loads while everything under the key silently does nothing) unless `strict_unknown_keys: true`. A repo with no `.coderabbit.yaml` passes, and says so. The schema is **vendored** at [`.github/coderabbit-config/`](.github/coderabbit-config) — no network fetch on the validation path, so an upstream schema change cannot redden the fleet without a reviewed PR here; `refresh-coderabbit-schema.yml` opens that PR weekly when upstream drifts. Setup: [docs/callers/coderabbit-config-validate.md](docs/callers/coderabbit-config-validate.md). Pin `workflows_ref` to the same ref as `uses:`; no secrets required. | | [`cursor-review-catalog-drift.yml`](.github/workflows/cursor-review-catalog-drift.yml) | **Internal to this repo — not `workflow_call`able.** Weekly (Mon 06:17 UTC) + `workflow_dispatch` drift check between the `cursor-review.yml` model pins and Cursor's live `cursor-agent models` catalog. Reads the pins *out of* `cursor-review.yml` (panel heredoc + `judge_model` default) rather than duplicating them, then reports: a **delisted pin** (urgent — consumer PRs are about to fail the review preflight; this also fails the run), a **pin whose catalog line now says NO-ZDR** (also urgent, and the quieter failure — nothing breaks, private review diffs just keep flowing to a model that may retain them), **unpinned same-lab catalog ids** (a review-me list, never an auto-recommendation — "newest highest-reasoning ZDR-eligible" is a human call, and NO-ZDR markers are surfaced verbatim; rendered one row per model *family*, newest first, since ids that differ only by a reasoning/speed tier are not separate candidates), **catalog ids from families the panel pins nothing from** (a quieter collapsed catch-all, never urgent — a lab is an id's first `-`/`.`-separated token, so a lab the panel *does* pin can only surface there once it rebrands under a new prefix, e.g. OpenAI's `o` series alongside `gpt-*`), and a **`last checked` audit date** older than 30 days (or future-dated). Findings land in one sticky issue (`[cursor-review catalog drift]`, label `cursor-review-catalog-drift`, updated in place, and closed only by a run that finds *no* drift at all — rare in practice, since a live catalog always offers unpinned tiers, so the issue's own footer states whether that report needs action now or is advisory) with the raw catalog folded in. Least privilege by construction: the job that pipes Cursor's installer into bash holds only `contents: read` and hands its rendered report to a separate `issues: write` job via an artifact. Comparison logic + tests live in [`.github/cursor-review/catalog-drift.py`](.github/cursor-review/catalog-drift.py). Requires `CURSOR_API_KEY`. | — | | [`refresh-reviewers.yml`](.github/workflows/refresh-reviewers.yml) | Companion to `assign-reviewers.yml` — a scheduled drift-detector that recomputes the caller's `.github/reviewers.yml` from git history (recency-decayed commit touches per rule bucket, same glob semantics as the assigner, collaborators only, bots and generated/churn paths excluded) and opens ONE idempotent single-file PR when the committed map drifts. The rewrite is surgical (only the `reviewers:`/`default_pool:` lists change — comments preserved), the PR body carries per-rule before/after scores plus a report-only taxonomy-gap section, and a rule with too few qualifiers is left unchanged. Never a live mutator. Engine + knob rationale in [`.github/refresh-reviewers/`](.github/refresh-reviewers). Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`, and `workflows_ref` (required) must pin the generator to the same SHA as `uses:`. | — | diff --git a/docs/callers/README.md b/docs/callers/README.md index 850f48e9..8967136f 100644 --- a/docs/callers/README.md +++ b/docs/callers/README.md @@ -13,6 +13,7 @@ per-workflow pages give you a complete, copy-pasteable caller: | `pr-risk.yml` | [pr-risk.md](pr-risk.md) | nothing | | `pr-derisk.yml` | [pr-derisk.md](pr-derisk.md) | `ANTHROPIC_API_KEY` | | `agents-md-integrity.yml` | [agents-md-integrity.md](agents-md-integrity.md) | nothing | +| `coderabbit-config-validate.yml` | [coderabbit-config-validate.md](coderabbit-config-validate.md) | nothing | | `assign-reviewers.yml` | [assign-reviewers.md](assign-reviewers.md) | `vars.APP_ID` + App key + `.github/reviewers.yml` | | `assign-prs-to-author.yml` | [assign-prs-to-author.md](assign-prs-to-author.md) | nothing | | `stale.yml` | [stale.md](stale.md) | `SLACK_BOT_TOKEN` (optional) | @@ -157,6 +158,7 @@ Enrolling a repo is **two steps**, and the second is the one people miss. | `pr-risk.yml` | `PR_RISK_CALLERS` | | `pr-derisk.yml` | `PR_RISK_CALLERS` (shared with `pr-risk.yml` — one entry per caller file) | | `agents-md-integrity.yml` | `AGENTS_MD_CALLERS` | + | `coderabbit-config-validate.yml` | `CODERABBIT_CONFIG_CALLERS` | | `assign-reviewers.yml` | `ASSIGN_REVIEWERS_CALLERS` | | `detect-unreviewed-merge.yml` | `DETECT_UNREVIEWED_MERGE_CALLERS` | diff --git a/docs/callers/coderabbit-config-validate.md b/docs/callers/coderabbit-config-validate.md new file mode 100644 index 00000000..f4483e5d --- /dev/null +++ b/docs/callers/coderabbit-config-validate.md @@ -0,0 +1,114 @@ +# `coderabbit-config-validate.yml` — fail a PR that breaks `.coderabbit.yaml` + +Read [the shared caller contract](README.md) first. + +## What it does + +Validates your repo's `.coderabbit.yaml` against CodeRabbit's published config +schema, on the PR that changes it. + +**Why that is worth a CI job.** CodeRabbit rejects an invalid `.coderabbit.yaml` +**whole** — it discards the entire file and reviews with org-wide UI defaults +instead. Every reviewer instruction, path filter, path instruction and WIP-skip +rule in it goes silently inert. The file still reads fine in review; only the +validator sees the loss. + +And the feedback is displaced by one PR: CodeRabbit validates the config on the +**base** branch, not the PR head. So the PR that breaks the file goes green, and +the breakage first surfaces on the *next* PR, attributed to a change that did not +cause it. The human loop here is not merely slow — it points at the wrong diff. + +Severity is split, mirroring what CodeRabbit itself does with each problem: + +| Problem | Result | Why | +|---|---|---| +| YAML parse error | **fails** | CodeRabbit can't read the file at all. | +| `maxLength` violation | **fails** | File-rejecting. The schema has 14 per-field caps, from 50 to 20,000 chars. | +| Type / enum error | **fails** | File-rejecting. | +| Unknown / additional property | **warns** | CodeRabbit *strips* an unrecognized key rather than rejecting the file — so the config loads, but everything under that key silently does nothing. Set `strict_unknown_keys: true` to fail instead. | +| No `.coderabbit.yaml` at all | **passes** | Reported in the log, so "no config here" never reads the same as "config validated clean". | +| `.coderabbit.yml` present under the default name | **validated, with a warning** | CodeRabbit honours both spellings, so the file that exists is the config in effect. Validating it is the point; the warning tells you to set `config_file` explicitly. | +| Config path outside the repo, not a regular file, or over 512 KiB | **errors (exit 2)** | "I could not check" must never look like a pass. Symlinks are resolved before the containment test. | + +The warning class is not cosmetic. The most common instance is a `tools:` block +written at the document root instead of under `reviews:`; the root is closed, so +the whole block is stripped and every setting in it reverts to the schema default +— which is often the *opposite* of what was written (`golangci-lint.enabled` +defaults to `true`, so a root-level `enabled: false` runs the linter it meant to +disable). The annotation names the offending key path and suggests where it +belongs. + +One limit worth knowing: the unknown-key check fires where the schema CLOSES an +object, which upstream does at the document root and for a handful of nested +objects. `reviews`, `chat`, `knowledge_base`, `code_generation` and the individual +tool configs are open, so a typo *inside* one (`reviews.profil`) is not flagged +even under `strict_unknown_keys`. What is caught is a key in the wrong PLACE — +the failure that actually recurs. + +The checker and the schema it validates against live in +[`.github/coderabbit-config/`](../../.github/coderabbit-config) and are loaded +from **this** repo at your pinned `workflows_ref` — never from your checkout — so +a PR cannot rewrite the check that judges it, nor swap the schema it is graded +against. + +## Prerequisites + +None. No secrets. + +## Caller + +`.github/workflows/coderabbit-config-validate.yml`: + +```yaml +name: CodeRabbit config + +on: + pull_request: + push: + branches: [main] # or [master] — your default branch + +jobs: + coderabbit-config: + permissions: + contents: read + uses: Comfy-Org/github-workflows/.github/workflows/coderabbit-config-validate.yml@ + with: + workflows_ref: +``` + +Then ask a maintainer to add your repo to the `CODERABBIT_CONFIG_CALLERS` roster +secret. Skipping that second step is the most repeated enrollment mistake: the pin +never moves, and the caller quietly drifts behind the reusable. + +## Required permissions + +```yaml +contents: read +``` + +## Inputs + +| Input | Default | Notes | +|---|---|---| +| `config_file` | `.coderabbit.yaml` | Point this at `.coderabbit.yml` if that's your spelling — if you don't, the checker finds it anyway and warns rather than reporting "absent". Must resolve inside the repo root (symlinks resolved). | +| `strict_unknown_keys` | `false` | Fail on an unknown/additional property instead of warning. Opt in once your config is clean, to keep it that way. | +| `workflows_ref` | *(required)* | **Set to your `uses:` SHA** — the checker and the vendored schema load from this ref. | + +## Gotchas + +**Do not add a `paths:` filter.** It is tempting — the check only concerns one +file — but a path-filtered check reports **skipped**, not **success**, on every +unrelated PR, which makes it useless as a required status check. The run is a +YAML parse and a schema walk over a few kilobytes; it is cheap enough to run +always. + +**Adopt on `pull_request` before making it required.** Three org repos were +invalid the day this landed. You want that visible on a PR first. + +**`strict_unknown_keys: true` is a one-way door for a repo that isn't clean yet.** +Fix the unknown keys first, then turn it on. + +**The schema is vendored, not fetched.** Validation never touches the network, so +an upstream schema change cannot turn your CI red without a reviewed PR here +first. `refresh-coderabbit-schema.yml` opens that PR weekly when upstream drifts; +merging it rolls the caller fleet forward automatically.